caput.dev configure your bot →

Troubleshooting

Organized by symptom. Find what's happening, then follow the fix.

Startup problems

Bot won't start — "config error" The bot can't read its configuration. Check that config.env exists in the working directory or that environment variables are set. Minimum required: CAPUT_TX_HASH and CAPUT_SELLER_WALLET. If neither is set, the bot enters bootstrap mode via the admin UI — that's normal for first run.

Bot won't start — "store error" The data directory can't be created or read. Check permissions on ~/.config/caput/ (or your CAPUT_DATA_DIR). The directory needs mode 0700. If you're running in a container, make sure the volume is mounted and writable.

Bot won't start — "usage sketch corrupted" The usage.cml file in the data directory has been tampered with or corrupted. The bot refuses to start because it can't verify your usage count. Restore from backup. If no backup exists, delete usage.cml — the bot will create a fresh sketch, but your usage count resets to zero. This is by design: the sketch is tamper-resistant, not tamper-proof.

Bot won't start — "xrpl client error" Can't connect to the XRPL node. Check your network connection. If on testnet: wss://s.altnet.rippletest.net:51233 must be reachable. If on mainnet: wss://xrplcluster.com must be reachable. If behind a corporate firewall, WebSocket connections on port 443/51233 may be blocked.

Bootstrap problems

"wallet not found on chain" The XRPL address you entered doesn't exist on the ledger. On mainnet, the account must be funded (minimum 1 XRP reserve). On testnet, use the faucet at faucet.altnet.rippletest.net to create a funded account.

Trust line check fails The bot can't find an RLUSD trust line on your wallet. Set one up in your wallet app: issuer rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De, currency USD. Wait a few seconds for the ledger to confirm, then click "Check" again.

"license verification failed" The transaction hash you entered isn't a valid Payment to the caput receiving address, or it hasn't been validated yet. Double-check the hash. If you just sent the payment, wait 5–10 seconds for ledger validation and try again.

Deploy problems

"no uses remaining" Your license's contract count is exhausted. Buy a new license bundle — uses stack on top of existing ones. The bot will always finish existing positions even if uses are zero; it only blocks new deploys.

Deploy hangs at step 5 (verify M configuration) The bot is checking that M's master key is disabled and the signer list is set to 2-of-2. If this hangs, the previous transactions (TrustSet, SignerListSet, AccountSet) may not have been validated yet. Wait 10–15 seconds. If it still hangs, check the bot's logs for XRPL errors.

Deploy fails at step 7 (AMM swap) The AMM swap couldn't execute. Possible causes: insufficient balance in seller's wallet, AMM pool has no liquidity, slippage exceeds tolerance. Check that the seller's wallet has enough XRP/RLUSD for the notional plus reserves (~2.6 XRP overhead). Check that the AMM pool for XRP/RLUSD exists and has depth.

Deploy fails at step 8–10 (escrow creation) EscrowCreate failed. Most common cause: insufficient balance. Each escrow locks funds from the source wallet plus 0.2 XRP reserve. Ensure the seller has (notional + 2.6 XRP) and the buyer has (margin + premium + 0.4 XRP).

Deploy fails at step 11–12 (pre-signing) The multisig pre-signing failed. This requires both parties to sign via their wallet adapters within the timeout (10 minutes). If one party doesn't sign in time, the session expires. Retry the deploy.

Runtime problems

Margin meter stuck at 0% The AMM rate hasn't moved, or the bot can't query the AMM. Check the events tab for rate query errors. On testnet, the AMM pool may have been drained or may not exist. On mainnet, this should work if the XRP/RLUSD pool has liquidity.

Position shows "settlement-pending" but nothing happens Both parties need to co-sign the settlement transactions. The bot constructs them and sends signing requests to both wallet adapters. Check the events tab for signing errors. If one party's wallet app isn't responding, the signing session will time out after 10 minutes. The position stays in "settlement-pending" until both sign.

Events show "hard-liq-fail — Variant A failed" The pre-signed swap-back couldn't deliver the required amount. This means the AMM rate has moved beyond 100% — it's a tail crash event. The bot automatically fires Variant B (partial delivery). Check the events for the Variant B result. If both fail, the position enters "failed" state and requires manual recovery.

Bot stopped polling (no events) The engine poll loop may have crashed. Check the bot's stdout/stderr logs. Common cause: XRPL WebSocket connection dropped. The bot should auto-reconnect, but if the host's network is unstable, connections can fail silently. Restart the bot.

Settlement problems

Settlement payment failed — "tecUNFUNDED_PAYMENT" M doesn't have enough funds to make the payment. This can happen if the AMM swap-back consumed more or less than expected, leaving M's balance off. Check M's balance on an XRPL explorer. The bot will retry with a spare Ticket if available. If all Tickets are consumed, both parties need to co-sign a fresh transaction manually.

Settlement payment failed — "tecPATH_PARTIAL" The path payment couldn't deliver the full amount. This is the slippage/liquidity case. The bot should retry with wider slippage tolerance. If retries fail, the parties co-sign a fresh transaction with adjusted parameters.

Cleanup failed — AccountDelete rejected AccountDelete requires M to have zero owner count (no trust lines, no signer list, no escrows, no tickets). The cleanup sequence removes these in order: unused Tickets → TrustSet 0 → SignerListSet quorum 0 → AccountDelete. If any prior step failed, the AccountDelete will be rejected. Check M's account on an explorer and manually submit the missing cleanup transaction.

Buyer disappeared after settlement started Funds sit in M. The seller retains whatever the pre-signed swap-back already delivered (in the hard liquidation case). Remaining funds in M require the buyer's signature to move. There is no automatic recovery. The buyer is also hurting themselves — they can't get their margin back without cooperating.

Wallet problems

Xaman payload times out The Xaman app didn't receive the push notification, or the user didn't sign within 10 minutes. Check that the bot has valid Xaman API credentials. Try again — the bot creates a new payload each time. If push doesn't work, the admin UI shows a QR code as fallback.

Crossmark/Gem extension not detected The browser extension must be installed and unlocked. The bot's UI triggers the extension via window.crossmark or window.gem. If the extension isn't detected, the UI falls back to displaying the unsigned transaction JSON for manual signing.

Manual paste: "invalid signed blob" The pasted blob isn't a valid signed XRPL transaction. Make sure you're pasting the full hex-encoded signed blob, not the unsigned transaction JSON or a hash. The signed blob starts with a hex string and is typically 200–400 characters long.

Recovery procedures

Restore from backup Stop the bot. Replace the .caput/ directory with your backup copy. Restart. Re-enter passphrase. The bot resumes from the backed-up state.

Rebuild from chain If the data directory is lost but you remember your wallet address:

caput-bot rebuild-state --address rYourWallet

This queries the chain for escrow and account objects associated with your wallet and re-derives what it can. Pre-signed blobs and fulfillments are not recoverable from the chain — those contracts will need CancelAfter refund (term + 30 days).

Manual escrow recovery If the bot is permanently lost and you need to recover funds:

Manual distribution from M If EscrowFinish succeeded but distribution didn't complete (funds sitting in M):