Installation Issues
npm install fails (TypeScript)
npm install fails (TypeScript)
npm install kaleido-sdk fails with errorsSolutions:- Ensure Node.js 18+ is installed:
node --version - Clear npm cache:
npm cache clean --force - Delete
node_modulesandpackage-lock.json, then reinstall - Try with a different package manager:
pnpm add kaleido-sdk
pip install fails (Python)
pip install fails (Python)
pip install kaleido-sdk failsSolutions:- Ensure Python 3.10+ is installed:
python --version - Use a virtual environment:
python -m venv .venv && source .venv/bin/activate - Upgrade pip:
pip install --upgrade pip - Try:
pip install kaleido-sdk --no-cache-dir
Module not found after installation
Module not found after installation
Cannot find module 'kaleido-sdk' or ModuleNotFoundErrorSolutions:- TypeScript: The SDK is ESM-only, so
tsconfig.jsonneeds"moduleResolution": "bundler","node16", or"nodenext". The legacy"node"setting ignores the package’sexportsfield and will not resolve it - Python: Verify you are in the correct virtual environment
- Verify the package is installed:
npm list kaleido-sdkorpip show kaleido-sdk
Runtime Errors
NetworkError: Connection refused
NetworkError: Connection refused
NetworkError when making API callsCauses:- API server unreachable
- Incorrect
baseUrl - Firewall blocking requests
- Verify the
baseUrlis correct and accessible - Check internet connectivity
- Try accessing the API URL in a browser:
https://api.signet.kaleidoswap.com/api/v1/market/assets - If behind a firewall, ensure outbound HTTPS is allowed
Node not configured
Node not configured
ConfigError (“Node API not configured…”) in TypeScript, or NodeNotConfiguredError in Python, when calling client.rln.* methodsCause: No nodeUrl / node_url was provided when creating the client.Solution:client.hasNode() / client.has_node() before calling RLN methods.QuoteExpiredError
QuoteExpiredError
QuoteExpiredError when calling initSwap / init_swap with an rfq_idCause: The quote’s expires_at time has passed.Solutions:- Get a fresh quote immediately before calling
initSwap— do not reuse anrfq_idacross user think-time - Use WebSocket streaming for always-current quotes
- Whitelist and execute promptly; the whole init → whitelist → execute sequence runs against one quote
ValidationError: Invalid amount
ValidationError: Invalid amount
ValidationError with amount-related messageCauses:- Amount below minimum or above maximum
- Wrong precision (sending display units instead of raw)
- Negative or zero amount
- Check min/max limits from the
listPairsresponse - Ensure you are sending raw amounts, not display amounts — convert with
parseRawAmount/parse_raw_amountfrom Utilities - Validate amounts before sending
TimeoutError
TimeoutError
TimeoutError on API callsCauses:- Slow network connection
- Server under heavy load
- Timeout too short
- Increase the timeout:
timeout: 60(seconds) - Check network connectivity
- Implement retry logic using
error.isRetryable()— see Error Handling
RateLimitError: 429 Too Many Requests
RateLimitError: 429 Too Many Requests
RateLimitError on repeated calls, typically while polling quotesCause: Too many requests in the rate-limit window.Solutions:- Back off and retry, honouring any
retry_afterthe response carries (in Python,is_retryable()returnsFalsefor rate limits, so back off manually) - Stream quotes over WebSocket instead of polling
getQuotein a loop - Cache
listAssets/listPairsrather than refetching them per operation
Swap Issues
SwapError on execute: swapstring not whitelisted
SwapError on execute: swapstring not whitelisted
initSwap succeeds, but executeSwap / execute_swap fails with SwapErrorCause: The swapstring returned by initSwap was never whitelisted on your own node, so the taker side cannot honour the HTLC.Solution: The three steps must run in order, and the whitelist step is on client.rln, not client.maker:client.maker.initSwap(...)→ returnsswapstringclient.rln.whitelistSwap(swapstring)→ your node accepts the swapclient.maker.executeSwap(...)→ the maker settles it
InsufficientBalanceError
InsufficientBalanceError
InsufficientBalanceError on init or executeCauses:- Not enough outbound capacity on the channel for the leg you are sending
- The dust reserve is not available on top of the swap amount
- Balance is on-chain rather than in a channel
- Check
client.rln.listChannels()for outbound capacity on the right asset, not just total balance - Confirm the amount is within the pair’s min/max from
listPairs - If capacity is short, order more inbound or outbound liquidity via LSPS1
Swap stuck in a pending state
Swap stuck in a pending state
executeSwap returned, but the assets have not arrivedSolutions:- Poll
client.maker.getAtomicSwapStatus(...)/get_atomic_swap_status(...)rather than assuming execute is terminal - Call
client.rln.refreshTransfers()/refresh_transfers()to advance pending RGB transfers - Check
client.rln.listSwaps()for the node’s own view of the swap
Version mismatch: unexpected response shape
Version mismatch: unexpected response shape
ValidationError, or a TypeScript field that is unexpectedly undefined) rather than returning a clean SDK errorCause: The SDK and the API it is talking to were generated against different spec versions. This is most common on the node side, where the RLN version is yours to control.Solutions:- Compare your node’s version against the one your SDK release targets — see RLN API Compatibility
- Upgrade the SDK:
npm install kaleido-sdk@latestorpip install --upgrade kaleido-sdk - Check the Changelog for breaking changes between your version and the current one — several releases added now-required request fields
WebSocket Issues
WebSocket not connecting
WebSocket not connecting
connected event never fires, or WebSocketErrorSolutions:- Verify the WebSocket URL is correct (should start with
wss://) - Ensure
enableWebSocket/enable_websocketwas called before streaming - Check that WebSocket connections are not blocked by firewall or proxy
- Try with a different client ID in the URL
No quotes received
No quotes received
quoteResponse / quote_response event never firesSolutions:- Verify the asset pair is valid and has available routes
- Check that the amount is within min/max limits
- Listen for
errorevents on the WSClient - Verify the connection is established (check
connectedevent)
Frequent disconnections
Frequent disconnections
- Check internet stability
- The WSClient auto-reconnects with exponential backoff
- Monitor
reconnectingevents to track attempts - If
maxReconnectExceededfires, manually reconnect:
TypeScript-Specific Issues
Type errors with OpenAPI types
Type errors with OpenAPI types
- Ensure you are importing types from
kaleido-sdk: - Check your TypeScript version is 5.0+
- If using strict mode, you may need to handle
undefinedexplicitly
ESM / CommonJS issues
ESM / CommonJS issues
ERR_REQUIRE_ESM or import syntax errorsSolutions:- The SDK is ESM-only. Ensure your project uses ESM:
"type": "module"inpackage.json- Or use
.mtsfile extension
- If you must use CommonJS, use dynamic import:
const sdk = await import('kaleido-sdk')
Python-Specific Issues
Pydantic validation errors
Pydantic validation errors
ValidationError from Pydantic when parsing API responsesSolutions:- Ensure
pydantic>=2.0is installed - Check that you are using the correct request format
- The API may have been updated — try updating the SDK:
pip install --upgrade kaleido-sdk
httpx connection errors
httpx connection errors
httpx.ConnectError or similarSolutions:- Check that the API URL is reachable
- If using a proxy, configure it via environment variables:
HTTP_PROXY,HTTPS_PROXY - Increase timeout if the connection is slow
Debugging
Enable Verbose Logging
Validate Configuration
Get Help
Check the FAQ for questions rather than errors. For anything else, report a problem through your preferred channel from the options below, including:- SDK version (
getVersion()/get_version()) - Language and runtime version (Node.js / Python)
- Error message and stack trace
- Minimal code to reproduce
- Environment (Regtest / Signet / Mainnet)