Skip to main content

​
Installation Issues

Symptoms: the install finished, but the shell cannot find kaleidoCause: the directory holding the launcher is not on your PATH. The installer says so on its last line: If 'kaleido' is not found yet, add <dir> to your PATH and restart your shell.Solutions:
  1. Restart the shell first — a new entry on PATH is not visible to an already-running session
  2. For a uv install, confirm the tool directory is on PATH: uv tool dir and uv tool list
  3. For the bootstrap installer, add the printed directory to PATH in your shell profile (~/.bashrc, ~/.zshrc)
  4. On Windows, use WSL — the shell bootstrap targets macOS, Linux, and WSL
Symptoms: ERROR: Could not find a version that satisfies the requirement kaleido-cliCause: the CLI is not published on PyPI. It installs from source only.Solution:
Or use the bootstrap installer, which prefers uv and falls back to an isolated virtual environment. See Installation.
Symptoms: the installer stops with that messageSolutions:
  1. Check what you have: python3 --version
  2. Install a newer Python, or let uv manage it: uv python install 3.12
  3. Re-run the installer once python3 resolves to 3.10 or newer

​
Setup And Environments

Symptoms: that message from any node lifecycle command, or from bare kaleido setupCause: the CLI shells out to docker compose, so both the binary and a running daemon are required.Solutions:
  1. Verify the client and the daemon: docker version — the “Server” block must be present
  2. Start Docker Desktop, or sudo systemctl start docker on Linux
  3. Confirm the Compose v2 plugin is available: docker compose version
  4. If you do not want Docker at all, run market-only setup: kaleido setup --mode market --defaults
Symptoms: No docker-compose.yml found in <dir>, followed by Run 'kaleido node create' to generate it., or Environment directory not found: <dir>Causes:
  • The environment was never created, or was created under a different base directory
  • spawn-dir in the config points somewhere else than where the environment lives
Solutions:
  1. List what the CLI can actually see: kaleido node list
  2. Check the base directory: kaleido config show — environments live under spawn-dir, default ~/.kaleido
  3. Recreate it: kaleido node create <name>
Symptoms: a lifecycle command refuses and lists the available environmentsCause: the environment name is auto-detected only when exactly one exists.Solution: name it explicitly.
The related message No environments found. Run 'kaleido node create' first. means the opposite problem — nothing has been created yet.
Symptoms: kaleido setup stops with that message and Choose a different environment name with --env-name to create a new node.Solutions:
  1. Reuse the existing environment: kaleido node up <name> then kaleido node use <name>
  2. Or create a separate one: kaleido setup --env-name taker-2
The interactive kaleido node create offers to overwrite the compose file instead, which leaves the data volumes untouched.
Symptoms: node up succeeds, node info failsSolutions:
  1. Check container state: kaleido node ps <name>
  2. Read the node’s own logs: kaleido node logs <name> --service rgb_node_1 --no-follow
  3. Look for a port conflict — node 1 binds 3001 and 9735, node 2 binds 3002 and 9736. If something else holds those ports, recreate the environment with different base ports through kaleido node create
  4. Give the node a moment after up: it has to open its database before serving requests

​
Node Connectivity

Symptoms: that message plus Use --node-url or: kaleido config set node-url http://localhost:3001Cause: the command needs a node, and no node URL was found in flags, environment, or config.Solutions:
  1. Point at an environment’s node: kaleido node use <name>
  2. Or set it directly: kaleido config set node-url http://localhost:3001
  3. Or override for one command: kaleido --node-url http://localhost:3002 wallet balance
Symptoms: a connection error from wallet, asset, channel, or payment, or balances that belong to a different nodeCauses:
  • The containers are not running
  • node-url still points at the node you used last
  • KALEIDO_NODE_URL is exported in the shell and silently overrides the stored config
Solutions:
  1. Confirm which node is active: kaleido config show, and kaleido node list — the active one is marked ●
  2. Start the environment: kaleido node up <name>
  3. Check for a stale override: echo $KALEIDO_NODE_URL
  4. Remember the precedence: flag, then environment variable, then config
Symptoms: kaleido node use <name> --node 2 refusesCause: --node is a 1-based index into the nodes the compose file actually defines.Solution: run kaleido node list to see how many nodes the environment has. To get more, recreate it and answer the node-count prompt with a higher number.The related No nodes found in environment '<name>'. Is the compose file present? means the compose file exists but defines no rgb_node_* service.
Symptoms: Error unlocking wallet: …, or node commands failing right after a restartCauses:
  • The node was restarted and never unlocked — unlock is needed every time
  • The bitcoind or indexer the unlock request points at is unreachable
  • The wallet was never initialised on this node
Solutions:
  1. Unlock it: kaleido node unlock
  2. If the services are the problem, follow the chain from the indexer instead of a bitcoind:
  3. If it was never initialised, run kaleido node init once first
  4. Confirm the result with kaleido node info
Symptoms: Error initializing wallet: …Causes:
  • The wallet was already initialised on this node — init runs once per node, not once per session
  • A restore was attempted with an invalid --mnemonic
Solutions:
  1. If the node is already initialised, skip straight to kaleido node unlock
  2. To start over from a clean node, kaleido node clean <name> deletes the volumes — irreversibly — and then init can run again
  3. When restoring, quote the mnemonic so the shell does not split it: --mnemonic "word1 word2 …"

​
Wallet And Assets

Symptoms: an insufficient-funds error from wallet send or asset sendCauses:
  • The balance is not confirmed yet
  • There are no spare UTXOs to allocate for the RGB assignment
  • The fee could not be covered on top of the amount
Solutions:
  1. Check what is actually spendable: kaleido wallet balance and kaleido wallet utxos
  2. Create colored UTXOs before RGB operations: kaleido wallet create-utxos --num 10 --size 3000
  3. Fund the node from the Mutiny faucet on signet, using an address from kaleido wallet address
  4. Check the going rate with kaleido wallet estimate-fee --blocks 6 and pass --fee-rate explicitly
Symptoms: kaleido asset transfers <asset-id> shows a transfer that never settlesSolutions:
  1. Advance pending transfers: kaleido asset refresh
  2. Resynchronise the RGB wallet: kaleido asset sync
  3. Inspect the state again: kaleido asset transfers <asset-id>
  4. Only if a transfer is genuinely dead, release its allocations: kaleido asset fail-transfers --batch-idx <idx>
If you have been passing --skip-sync, drop it: the command is returning cached state on purpose.
Symptoms: File not found: <path> or Invalid JSON: …Cause: asset send-batch takes a path to a JSON file describing the recipients, not inline flags.Solution:
Check the path relative to your current directory, and validate the file before retrying.
Symptoms: wallet backup or wallet restore refuses under --agentCause: the destination path is a positional argument, and prompts are disabled.Solution: pass it explicitly, along with the password.
Restore overwrites the current node data, so run it deliberately.

​
Channels And LSP Orders

Symptoms: channel open or peer connect refusesCause: the peer was passed as a bare pubkey. Interactively the CLI asks for the address; non-interactively it requires the full form.Solutions:
  1. Use the complete peer string: kaleido channel open 03abc...@peer.host:9735 --capacity 100000
  2. Connect first and confirm reachability: kaleido peer connect 03abc...@peer.host:9735 then kaleido peer list
Related non-interactive refusals: PEER argument is required in non-interactive mode. and --capacity is required in non-interactive mode.
Symptoms: a colored-channel command refuses before contacting the nodeCause: asset amounts are meaningless without the asset they refer to. The same rule applies to --push-asset-amount, and to --lsp-asset-amount / --client-asset-amount on LSP orders.Solution:
On LSP orders, --lsp-asset-amount is required when --asset-id is set. and --client-asset-amount must be less than or equal to --lsp-asset-amount. are the two constraints to respect.
Symptoms: channel close <channel-id> refusesCause: closing needs both the channel ID and the peer pubkey.Solution:
Add --force only when the peer is unresponsive: a unilateral close locks funds until the timelock expires.
Symptoms: channel order create or estimate-fees refuses the assetCause: the LSP only opens colored channels for the assets it supports.Solution: list what it offers and use one of those asset IDs.
LSP did not report a connection URL. points at the other side of the same conversation — the LSP metadata came back without a peer address, so the order cannot proceed.
Symptoms: channel order pay returns This order is not awaiting a wallet payment. Current payment state: <state>Causes:
  • The order was already paid
  • It expired before funding
  • It is waiting on a rate decision rather than a payment
Solutions:
  1. Read the current state: kaleido channel order get <order-id> --access-token <token>
  2. If it is waiting on a rate, decide: kaleido channel order decide <order-id> --accept
  3. If it expired, create a new order — --funding-within and --expiry-blocks control those windows
  4. Non-interactively, pick the funding source explicitly, or you will get Specify exactly one of --onchain or --offchain in non-interactive mode.

​
Market And Swaps

Symptoms: Pair 'BTC/USD' not found. Use 'kaleido market pairs' to list available pairs.Causes:
  • A typo, or a ticker that is not listed
  • The pair is written the wrong way round — order matters
Solutions:
  1. List them: kaleido market pairs
  2. Use the exact BASE/QUOTE ticker from that output
No trading pairs are currently available. is different: the maker returned an empty list, so the problem is upstream rather than in your command.
Symptoms: a quote or swap command refuses, or Provide --from-amount or --to-amount in non-interactive mode.Cause: a quote is anchored on one side only — you fix what you send or what you receive, and the maker prices the other.Solutions:
  1. Pass exactly one of the two
  2. Remember these are display units: --from-amount 0.001 is 0.001 BTC, not 1000 sat
  3. If the amount is rejected as invalid, check the pair’s limits in kaleido market pairs
Symptoms: that message, or Swapstring fields must not be empty or whitespace., or Swapstring contains invalid numeric fields.Cause: the swapstring was truncated or mangled. Its shape is:
Solutions:
  1. Copy the whole string from the swap atomic init output, without wrapping it across lines
  2. Quote it, so the shell does not touch it: --swapstring '30/rgb:abc.../10/rgb:def.../600/<hash>'
  3. Or skip the manual step entirely with kaleido swap atomic run <pair>
Symptoms: Auto-whitelist validation failed: …, or messages like Swapstring from_amount 30 does not match quote amount 31.Cause: before whitelisting on your node, the CLI checks the swapstring against the quote you accepted. A mismatch means the swapstring belongs to a different swap, or the quote moved.Solutions:
  1. Re-run swap atomic init and use the swapstring and payment hash from that same response — never mix them across runs
  2. Do not reuse an old swapstring after a re-quote
  3. Maker returned no swap payload for --payment-hash; refusing to auto-whitelist. means the maker has no swap for that payment hash: check it with kaleido swap atomic status <payment-hash>
Symptoms: swap atomic init succeeded, swap atomic execute failsCause: the taker node has to accept the swap before the maker can settle it, and that step runs against your node, not the maker.Solution: the three steps must run in order.
Or let the CLI do it: add --auto-whitelist to execute, or use kaleido swap atomic run <pair>.
Symptoms: execute returned, but the assets have not arrivedSolutions:
  1. Poll the maker’s view: kaleido swap atomic status <payment-hash>
  2. Poll your node’s view: kaleido node swap status <payment-hash> --taker
  3. List what the node knows: kaleido node swap list
  4. Advance pending RGB transfers: kaleido asset refresh
Insufficient outbound capacity on the leg you are sending is the usual cause. Check kaleido channel list for capacity on that specific asset, not just the total balance.

​
Scripting And Automation

Symptoms: a script stalls with no outputCause: the command is waiting on an interactive prompt that nothing will answer.Solution: run it with --agent, which turns every prompt into an error instead:
You will then get an explicit refusal such as PAIR argument is required in non-interactive mode. or <option> is required in non-interactive mode., naming exactly what to pass.
Symptoms: one of --yes is required in non-interactive mode to accept the quoted price., … to accept the RFQ price., … to pay the order., or the JSON-mode variantsCause: anything that spends money or accepts a price asks for confirmation, and there is no one to ask.Solutions:
  1. Add --yes once you are satisfied with the parameters
  2. Price-check first with kaleido market quote or kaleido channel order estimate-fees, then execute with --yes
  3. kaleido node clean and kaleido config reset take --yes too
Symptoms: Must specify exactly one of --accept or --reject, Must specify at most one of --taker or --maker, or Specify exactly one of --onchain or --offchain in non-interactive mode.Cause: these pairs are choices, not toggles, and the CLI refuses to guess when neither or both are given.Solution: pass exactly one. Interactively, omitting both makes the CLI prompt instead.

​
Debugging

When a command fails and the message is not enough, work outward from the CLI’s own view of the world:
Check echo $KALEIDO_NODE_URL and echo $KALEIDO_API_URL as well: an exported variable overrides the stored config and is easy to forget.

​
Get Help

Check the FAQ for questions rather than errors, and Additional Resources for upstream documentation and links. For anything else, report a problem through your preferred channel from the options below, including:
  1. How you installed the CLI, and the output of uv tool list (there is no --version flag)
  2. Python version (python --version) and your operating system
  3. The exact command you ran, plus its output with --json added
  4. Whether the node is a local Docker environment or a remote one, and the network
  5. kaleido config show and kaleido node ps output, with passwords removed

Telegram Community

Ask the community.

GitHub Issues

Report a bug on the relevant repository.

Email Support

Direct support for urgent issues.