Skip to main content

​
Desktop Application

​
Installation & Startup Issues

Symptoms: Double-clicking the application does nothing or shows an error.Solutions:
  1. macOS: Check if the app is blocked by Gatekeeper
    • Go to System Preferences → Security & Privacy
    • Click “Open Anyway” if you see a message about KaleidoSwap
  2. Windows: Run as Administrator
    • Right-click the app → Run as Administrator
    • Check Windows Defender hasn’t quarantined the file
  3. Linux: Check execution permissions
  4. Check system requirements:
    • 4GB RAM minimum
    • 500MB free disk space
    • Supported OS version (macOS 12+, Windows 10+ 64-bit, Ubuntu 22.04+)
Symptoms: SHA256 checksum doesn’t match the published hash.Solutions:
  1. Re-download the application from the official GitHub releases
  2. Ensure you’re downloading the correct file for your platform
  3. Use a reliable download connection (corrupted downloads can cause mismatches)
  4. Verify you’re comparing against the correct version’s checksum
See the Binary Verification guide for detailed steps.
Symptoms: Application opens briefly then closes, or shows a crash dialog.Solutions:
  1. Check the log files:
    • macOS: ~/Library/Logs/com.kaleidoswap.dev/
    • Windows: %APPDATA%\com.kaleidoswap.dev\logs
    • Linux: ~/.local/share/com.kaleidoswap.dev/logs
  2. Common causes:
    • Corrupted configuration: Delete the config file and restart
    • Port conflict: Another app is using the required ports (9735, 3001)
    • Missing dependencies: Reinstall the application
  3. If the crash persists, attach the most recent log file from the directory above when contacting support or opening a GitHub issue.

​
Node & Connection Issues

Symptoms: Error messages about LSP connection, or unable to open channels.Solutions:
  1. Check your internet connection
    • Ensure you have a stable internet connection
    • Try accessing other websites to verify connectivity
  2. Verify LSP URL
    • Default: https://api.signet.kaleidoswap.com
    • Check Settings → LSP Configuration
  3. Firewall/VPN issues
    • Disable VPN temporarily to test
    • Allow KaleidoSwap through your firewall
    • Required ports: 9735 (Lightning P2P), 3001 (node API)
  4. Check LSP status
    • Visit the LSP’s status page or contact support
    • Try switching to a different LSP if available
Symptoms: Blockchain sync taking hours or appearing stuck.Solutions:
  1. Normal behavior: Initial sync can take 30 minutes to several hours depending on:
    • Your internet speed
    • Your system’s disk speed
    • Network congestion
  2. Check sync progress:
    • Look for block height in the UI
    • Compare against current network height
  3. Stuck sync troubleshooting:
    • Restart the application
    • Check available disk space (need at least 10GB free)
    • Clear peer list and reconnect
    • Check firewall isn’t blocking P2P connections
Symptoms: “No peers connected” or low peer count.Solutions:
  1. Wait: Peer discovery can take a few minutes
  2. Check network settings:
    • Ensure UPnP is enabled on your router (for incoming connections)
    • Manually forward port 9735 if UPnP unavailable
  3. Bootstrap nodes:
    • The app should connect to bootstrap nodes automatically
    • If not, check your internet connection and firewall
  4. Network selection:
    • Verify you’re on the correct network (Mainnet/Testnet/Signet/Regtest)
    • Peers must be on the same network

​
Wallet & Asset Issues

Symptoms: Expecting funds but balance shows 0 or is incorrect.Solutions:
  1. Wait for sync: Balance won’t show until node is fully synced
  2. Check the correct network: Ensure you’re on the network where you have funds
  3. Verify wallet recovery: If you restored from seed, ensure you used the correct mnemonic
  4. Check asset vs BTC balance: Toggle between Bitcoin and RGB asset views
  5. Refresh: Try restarting the application
Symptoms: Password not working, wallet stays locked.Solutions:
  1. Verify password: Passwords are case-sensitive
  2. Caps Lock: Check if Caps Lock is accidentally on
  3. Different keyboard layout: Ensure same keyboard layout as when password was set
  4. Wallet recovery: If password is truly lost, you’ll need to recover using your mnemonic seed
  5. Contact support: As a last resort, contact support with your wallet public key (never share private keys)
Symptoms: Received an asset but it doesn’t show in your wallet.Solutions:
  1. Wait for confirmation: RGB asset transfers require Bitcoin confirmations
  2. Import consignment: You may need to manually import the consignment data
  3. Check asset ID: Verify you’re looking at the correct asset
  4. Refresh asset list: Settings → Assets → Refresh
  5. Verify sender completed transfer: Contact sender to confirm they finished the send process

​
Channel Operations

Symptoms: Channel order fails or gets stuck.Solutions:
  1. Check order status: Use Order ID to check status via API or support
  2. Common failure reasons:
    • Insufficient funds: Need to cover channel amount + fees
    • Payment timeout: Invoice expired before payment
    • Invalid parameters: Check min/max channel sizes
    • LSP unavailable: Temporary LSP downtime
  3. Refund process:
    • If order fails, refunds are automatic to your refund address
    • Refunds may take 6+ confirmations to appear
  4. Retry:
    • Wait a few minutes and try again
    • Reduce channel size if at maximum
    • Verify sufficient inbound liquidity
Symptoms: Channel exists but cannot send/receive payments.Solutions:
  1. Wait for confirmations: Channels need blockchain confirmations to become active
    • Typically 3-6 confirmations required
    • Check confirmation count in channel details
  2. Peer offline: Your channel partner needs to be online
    • Wait for peer to come back online
    • Check “Last Seen” timestamp
  3. Channel reserves: Cannot spend below channel reserve amount
    • Lightning channels require keeping a reserve balance
    • This is normal protocol behavior
  4. Force close: If channel is permanently stuck, you can force-close
    • This puts funds back on-chain after a delay
    • Should be last resort
Symptoms: Channel opened but RGB assets not yet delivered.Solutions:
  1. Normal delay: Asset delivery via keysend can take a few minutes
    • Automatic retry mechanism in place
    • Can take up to 30 minutes in some cases
  2. Check delivery status:
    • Order details show asset delivery status
    • Statuses: PENDING → IN_PROGRESS → COMPLETED
  3. Manual retry:
    • Use “Retry Delivery” button if available
  4. Failed delivery:
    • Contact LSP support with Order ID
    • Refund may be available if delivery cannot complete

​
Trading & Swaps

Symptoms: Swap doesn’t complete or expires.Solutions:
  1. Quote expiration: RFQ quotes are short-lived — about 60 seconds by default, and each quote carries its own expires_at
    • Complete swap before expiration
    • Request new quote if expired
  2. Rate changed: Market rate changed significantly
    • Accept new rate when prompted
    • Or cancel and get refund
  3. Payment routing failed: Lightning payment couldn’t find a route
    • Try smaller amount
    • Open additional channels for more liquidity
    • Wait and retry
  4. Swap stuck:
    • Check swap status: POST /api/v1/swaps/atomic/status (by payment hash)
    • Contact support with the payment hash for assistance
Symptoms: Final price different from expected.Solutions:
  1. Check quote details: Review the RFQ response carefully
    • from_amount vs to_amount
    • Applied fees
    • Precision of assets
  2. Fee structure:
    • Base fee + variable fee
    • Fee asset and precision
    • Total fee shown in quote
  3. Precision confusion:
    • BTC uses 8 decimals
    • USDT typically uses 6 decimals
    • Check asset precision in glossary
  4. Slippage:
    • For market orders, price can move slightly
    • Use limit orders if you need exact price
For failed trades, wallet restore, and LSP connection questions, see Desktop App Troubleshooting.

​
Browser Extension

The cases below are specific to how the closed beta is installed and how its accounts are backed.

​
Installation & Updates

Symptoms: chrome://extensions rejects the folder, or a working extension stops loading after a while.Solutions:
  1. Select the right folder: Choose the folder that contains manifest.json. If the archive has a dist folder, select dist.
  2. Don’t move or delete the extracted folder: The browser loads the extension from that path every time. Moving it to another disk, renaming it, or clearing a Downloads folder breaks the install.
  3. Extract first: Point the browser at the extracted folder, not at the zip.
  4. Re-add it: Remove the broken card in chrome://extensions and load the folder again. Your wallet is not stored in that folder, so this does not touch your funds.
Symptoms: You installed a newer zip but the extension still behaves like the old version.Solutions:
  1. Closed beta builds do not auto-update — there is no store listing to push them.
  2. After extracting the new zip, go to chrome://extensions and click Reload on the KaleidoSwap card.
  3. If you extracted into a different folder, remove the old unpacked extension and load the new folder instead — otherwise the browser keeps running the old one.
  4. Confirm the version under Settings > About.
Symptoms: The beta zip cannot be loaded at all.Solutions:
  1. The closed beta targets Chromium-based browsers: Chrome, Brave, Edge, Opera.
  2. Firefox is not part of the first closed beta unless a Firefox build is provided, and Safari is not supported yet.
  3. Developer mode must be toggled on in chrome://extensions before Load unpacked appears.
  4. Install only archives from the official invite or support channel — never a forwarded copy.

​
Accounts & Balances

Symptoms: RGB balances were visible, then vanished once an RGB Lightning Node was connected.Explanation: The node-less RGB-L1 account and the RLN account are mutually exclusive backings for RGB assets. Connecting RLN replaces the node-less backing, so you are looking at a different account — the RGB-L1 state has not been lost.Solutions:
  1. Disconnect RLN in Settings > Accounts > RGB to return to the node-less RGB-L1 backing.
  2. Decide which backing you want: node-less for RGB on Bitcoin L1, RLN for RGB Lightning channels and maker-based swaps.
  3. Before switching, make sure the backing you are leaving is backed up — RGB-L1 to its cloud (VSS) and local backups, RLN to the node’s own backup material.
Symptoms: Spark, Arkade, and Liquid balances came back after importing the recovery phrase, but RGB assets did not.Solutions:
  1. RGB-L1 state is not derived from the recovery phrase — it is restored from the encrypted cloud (VSS) backup, and only if you explicitly consent at that onboarding step. Skipping the prompt leaves the state behind.
  2. Re-import the wallet and accept the restore prompt when it appears.
  3. If you use RLN instead, RGB state must be recovered from the node’s own backup material, not from the extension.
Symptoms: You restored using an nsec1… key and the wallet is empty.Solutions:
  1. A Nostr key does not control funds. Importing one only replaces the Nostr identity.
  2. Always restore with the BIP39 recovery phrase — it is what derives the Spark, Arkade, Liquid, and RGB-L1 accounts.
  3. Re-import using the recovery phrase; you can import the Nostr key afterwards from Settings.

​
Swaps & Bridge

Symptoms: The swap screen refuses an amount you appear to hold.Solutions:
  1. The amount input is gated by your spendable balance for the source asset, not the total balance, so you cannot quote more than the wallet can actually send.
  2. On-chain sends also reserve the network fee — Max accounts for this automatically.
  3. Check that the balance is on the account the selected route uses; balances are tracked per layer.
Symptoms: A quoted swap ends in failure rather than filling at a worse rate.Solutions:
  1. This is slippage protection working as intended: the minimum output is derived from your configured tolerance, and the swap fails rather than executing beyond it.
  2. Re-quote — quotes expire, and the rate may have moved since.
  3. Adjust your slippage tolerance if the market is genuinely volatile, or reduce the size.
Symptoms: You closed the extension mid-bridge and the order is no longer on screen.Solutions:
  1. Bridge orders are saved locally as a session. Reopening the bridge screen restores the pending order and resumes tracking, even after the service worker restarts.
  2. Completed and failed orders show a final status with the relevant transaction references.
  3. Deposits confirm on the source chain first — an order can sit in progress while that happens.
For node connection, payment, and DApp provider problems, see KaleidoSwap Extension Troubleshooting.

​
API & Integration

​
Authentication & Connection

Symptoms: API returns 401 status code.Solutions:
  1. Bearer token: Ensure you’re sending authentication token correctly
  2. Token expiration: Tokens may expire - obtain a new one
  3. Incorrect endpoint: Verify you’re using the correct API base URL
    • Signet (live): https://api.signet.kaleidoswap.com/api/v1
    • Mainnet: https://api.kaleidoswap.com/api/v1 (coming soon)
Symptoms: API returns 422 with validation errors.Solutions:
  1. Check request body: Ensure all required fields are present
  2. Data types: Verify integers, strings, booleans are correct type
  3. Field validation: Check min/max values, formats
  4. Read error details: The response includes which fields failed validation
Example error response:
Symptoms: Browser blocks API requests with CORS error.Solutions:
  1. Use backend: Make API calls from your backend, not frontend
    • CORS is disabled for security on most endpoints
    • Browser-based apps need a backend proxy
  2. Development workaround:
    • Use browser CORS plugin (development only)
    • Configure your dev server as proxy
  3. Production: Always use server-side API calls

​
RFQ & Order Issues

Symptoms: Using RFQ ID returns error about expiration.Solutions:
  1. Check expires_at: Quotes are valid for about 60 seconds by default; always read the quote’s own expires_at rather than assuming a fixed window
  2. Request new quote: Call /api/v1/market/quote again
  3. Faster integration: Minimize time between quote and order creation
  4. Use expiration time: Build UI countdown showing time remaining
Symptoms: Order doesn’t progress from PENDING_PAYMENT or other status.Solutions:
  1. Payment required: Check if you need to pay an invoice or send to an address
  2. Check payment status:
  3. Automatic transitions: Some states transition automatically
    • PENDING_PAYMENT → PAID (after payment confirmed)
    • CHANNEL_OPENING → COMPLETED (after channel opens)
  4. Timeouts: Orders expire if not paid within time limit
    • Check expires_at field
    • Unpaid orders auto-expire and refund
For the full list of HTTP status codes, the error response format, and retry strategies, see Error Handling in the API Reference.

​
SDK

Both SDK guides cover TypeScript and Python side by side — every example shows both. Pick by what you need:

Error Handling

Which exceptions the SDK raises, how to catch them, retry patterns, and HTTP status mapping.

SDK Troubleshooting

Symptom-to-fix for install failures, connection errors, WebSocket problems, and language-specific gotchas.
Quick tips:
  • Catch KaleidoError — every SDK exception extends it, and isRetryable() / is_retryable() tells you whether a retry is safe
  • Enable debug logging for full request and response detail
  • Check your runtime: Node.js 18+ / Python 3.10+

​
General Best Practices

Check Logs First

Most issues can be diagnosed from log files. Enable debug logging when troubleshooting.

Verify Network

Ensure you’re on the correct network (Mainnet, Testnet, Signet, Regtest) for your use case.

Keep Updated

Use the latest version of Desktop App and SDKs for bug fixes and improvements.

Test on Testnet

Always test new integrations on Testnet before using real funds on Mainnet.

​
Still Need Help?

If these troubleshooting steps don’t resolve your issue:
1

Check the FAQ for your surface

Each product keeps its own reference: Desktop App Troubleshooting, KaleidoSwap Extension Troubleshooting, KaleidoSDK Troubleshooting, and API Error Handling.
2

Search Documentation

Use the search bar to find specific topics in the documentation.
3

Check GitHub Issues

See if others have reported the same problem in the repository for the component you are running. All repositories live under the KaleidoSwap organization.
4

Contact Support

Reach out via:
Never share your private keys or mnemonic seed with anyone, including support staff. Legitimate support will never ask for this information.