Skip to main content

Installation Issues

Symptoms: npm install kaleido-sdk fails with errorsSolutions:
  1. Ensure Node.js 18+ is installed: node --version
  2. Clear npm cache: npm cache clean --force
  3. Delete node_modules and package-lock.json, then reinstall
  4. Try with a different package manager: pnpm add kaleido-sdk
Symptoms: pip install kaleido-sdk failsSolutions:
  1. Ensure Python 3.10+ is installed: python --version
  2. Use a virtual environment: python -m venv .venv && source .venv/bin/activate
  3. Upgrade pip: pip install --upgrade pip
  4. Try: pip install kaleido-sdk --no-cache-dir
Symptoms: Cannot find module 'kaleido-sdk' or ModuleNotFoundErrorSolutions:
  • TypeScript: The SDK is ESM-only, so tsconfig.json needs "moduleResolution": "bundler", "node16", or "nodenext". The legacy "node" setting ignores the package’s exports field and will not resolve it
  • Python: Verify you are in the correct virtual environment
  • Verify the package is installed: npm list kaleido-sdk or pip show kaleido-sdk

Runtime Errors

Symptoms: NetworkError when making API callsCauses:
  • API server unreachable
  • Incorrect baseUrl
  • Firewall blocking requests
Solutions:
  1. Verify the baseUrl is correct and accessible
  2. Check internet connectivity
  3. Try accessing the API URL in a browser: https://api.signet.kaleidoswap.com/api/v1/market/assets
  4. If behind a firewall, ensure outbound HTTPS is allowed
Symptoms: 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:
Always check client.hasNode() / client.has_node() before calling RLN methods.
Symptoms: QuoteExpiredError when calling initSwap / init_swap with an rfq_idCause: The quote’s expires_at time has passed.Solutions:
  1. Get a fresh quote immediately before calling initSwap — do not reuse an rfq_id across user think-time
  2. Use WebSocket streaming for always-current quotes
  3. Whitelist and execute promptly; the whole init → whitelist → execute sequence runs against one quote
Symptoms: ValidationError with amount-related messageCauses:
  • Amount below minimum or above maximum
  • Wrong precision (sending display units instead of raw)
  • Negative or zero amount
Solutions:
  1. Check min/max limits from the listPairs response
  2. Ensure you are sending raw amounts, not display amounts — convert with parseRawAmount / parse_raw_amount from Utilities
  3. Validate amounts before sending
Symptoms: APIError with status 401Cause: Invalid or missing API key.Solutions:
  1. Check that apiKey / api_key is set correctly
  2. Verify the key is valid and not expired
  3. Some endpoints may not require an API key — check the API Reference
Symptoms: TimeoutError on API callsCauses:
  • Slow network connection
  • Server under heavy load
  • Timeout too short
Solutions:
  1. Increase the timeout: timeout: 60 (seconds)
  2. Check network connectivity
  3. Implement retry logic using error.isRetryable() — see Error Handling
Symptoms: RateLimitError on repeated calls, typically while polling quotesCause: Too many requests in the rate-limit window.Solutions:
  1. Back off and retry, honouring any retry_after the response carries (in Python, is_retryable() returns False for rate limits, so back off manually)
  2. Stream quotes over WebSocket instead of polling getQuote in a loop
  3. Cache listAssets / listPairs rather than refetching them per operation

Swap Issues

Symptoms: 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:
  1. client.maker.initSwap(...) → returns swapstring
  2. client.rln.whitelistSwap(swapstring) → your node accepts the swap
  3. client.maker.executeSwap(...) → the maker settles it
See How to Swap for the full sequence.
Symptoms: 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
Solutions:
  1. Check client.rln.listChannels() for outbound capacity on the right asset, not just total balance
  2. Confirm the amount is within the pair’s min/max from listPairs
  3. If capacity is short, order more inbound or outbound liquidity via LSPS1
Symptoms: executeSwap returned, but the assets have not arrivedSolutions:
  1. Poll client.maker.getAtomicSwapStatus(...) / get_atomic_swap_status(...) rather than assuming execute is terminal
  2. Call client.rln.refreshTransfers() / refresh_transfers() to advance pending RGB transfers
  3. Check client.rln.listSwaps() for the node’s own view of the swap
Symptoms: A call fails on parsing (Pydantic 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:
  1. Compare your node’s version against the one your SDK release targets — see RLN API Compatibility
  2. Upgrade the SDK: npm install kaleido-sdk@latest or pip install --upgrade kaleido-sdk
  3. Check the Changelog for breaking changes between your version and the current one — several releases added now-required request fields

WebSocket Issues

Symptoms: connected event never fires, or WebSocketErrorSolutions:
  1. Verify the WebSocket URL is correct (should start with wss://)
  2. Ensure enableWebSocket / enable_websocket was called before streaming
  3. Check that WebSocket connections are not blocked by firewall or proxy
  4. Try with a different client ID in the URL
Symptoms: quoteResponse / quote_response event never firesSolutions:
  1. Verify the asset pair is valid and has available routes
  2. Check that the amount is within min/max limits
  3. Listen for error events on the WSClient
  4. Verify the connection is established (check connected event)
Symptoms: WebSocket disconnects and reconnects frequentlySolutions:
  1. Check internet stability
  2. The WSClient auto-reconnects with exponential backoff
  3. Monitor reconnecting events to track attempts
  4. If maxReconnectExceeded fires, manually reconnect:

TypeScript-Specific Issues

Symptoms: TypeScript compiler errors about incompatible typesSolutions:
  1. Ensure you are importing types from kaleido-sdk:
  2. Check your TypeScript version is 5.0+
  3. If using strict mode, you may need to handle undefined explicitly
Symptoms: ERR_REQUIRE_ESM or import syntax errorsSolutions:
  1. The SDK is ESM-only. Ensure your project uses ESM:
    • "type": "module" in package.json
    • Or use .mts file extension
  2. If you must use CommonJS, use dynamic import: const sdk = await import('kaleido-sdk')

Python-Specific Issues

Symptoms: ValidationError from Pydantic when parsing API responsesSolutions:
  1. Ensure pydantic>=2.0 is installed
  2. Check that you are using the correct request format
  3. The API may have been updated — try updating the SDK: pip install --upgrade kaleido-sdk
Symptoms: httpx.ConnectError or similarSolutions:
  1. Check that the API URL is reachable
  2. If using a proxy, configure it via environment variables: HTTP_PROXY, HTTPS_PROXY
  3. 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:
  1. SDK version (getVersion() / get_version())
  2. Language and runtime version (Node.js / Python)
  3. Error message and stack trace
  4. Minimal code to reproduce
  5. Environment (Regtest / Signet / Mainnet)

Telegram Community

Ask the community.

GitHub Issues

Report a bug on the relevant repository.

Email Support

Direct support for urgent issues.