Skip to content

Troubleshooting ​

Every error the CLI refuses with is a designed signal, not a bug to work around. Grouped by what you were trying to do. Exit codes: 0 success; non-zero refusal (per-command codes where documented, e.g. tx verify semantics or the MCP execution-mode exit 47).

Install & update ​

SymptomCauseFix
furlpay: command not foundnpm global bin not on PATHnpm config get prefix → add its bin to PATH, or reinstall with the installer script
Install script warns about mirrorsunofficial registry overrideremove the mirror from .npmrc; the script warns rather than proceeding silently
furlpay update stallsnpm global permissionsuse the installer script (never sudo) or npm config set prefix to a user-writable path

Authentication & credentials ​

SymptomCauseFix
Device login URL doesn't openheadless boxset FURLPAY_NO_BROWSER=1 and open the printed URL anywhere
login --key refusedsecret on argvpipe it: `printf '%s' "$KEY"
Hosted commands 401expired session cookiefurlpay login again; the cookie only attaches to furlpay.com over TLS/loopback — check --api-base if you overrode it
credential-less request warning--api-base pointed at a non-FurlPay hostby design: cookies never leave the furlpay.com/loopback boundary

Wallets & signing ​

SymptomCauseFix
Ledger probe finds nothingapp not open / USB HID permissionsopen the Stellar app on the device; on Linux check udev rules
"Fail closed without signer" on HLP/perpsno signer configuredexport HYPERLIQUID_PRIVATE_KEY (or ETH_PRIVATE_KEY) — there is deliberately no simulated fallback
Order refused: LIVE_EXECUTION_DISABLEDFURLPAY_LIVE master gateset FURLPAY_LIVE=1 and have the per-surface credential; the gate is on top of, not instead of, credentials
Order refused by risk enginemargin/notional/turnover/peg guardread the reason field: peg halts carry PEG_FEED_UNAVAILABLE when the feed (not the peg) is the problem

MCP agents ​

SymptomCauseFix
EXECUTION_MODE_REQUIREDread-only defaultthis is the designed default; add --enable-execution + a policy only if you intend value movement
Server exits 47 on --enable-executionno agent policy on diskrun furlpay wallet agent-keygen first (recipe 8)
TWO_PHASE_REQUIREDmutating tool called directlypreview via furlpay_preview_execution, then furlpay_confirm_execution {executionHash}
Confirm fails after 10 minpreview TTL expiredre-preview; hashes are single-use by design
Tool missing from tools/listit is value-moving and you are read-onlystructural absence — see MCP tools

Network surfaces ​

SymptomCauseFix
tx verify returns UNAVAILABLEHorizon outagean outage is never evidence about the transaction; retry later
solana commands fail with SOLANA_RPC_INSECURE_URLnon-https RPCuse https endpoints only
INVALID_SOLANA_ADDRESSnot base58 (0/O/I/l present, wrong length)validate the address before the call
Oracle DISAGREEMENT (exit 1)sources differ beyond the asset budgetinspect the printed per-source readings; the CLI refuses to blend disagreeing prices
Oracle UNAVAILABLE (exit 2)no source answered sanelycheck network/egress; nothing is guessed — that is the point
Pyth provider listed (none)public Hermes is auth-gatedconfigure FURLPAY_PYTH_HERMES_URL + FURLPAY_PYTH_FEED_IDS with a gateway you are authorized to use
Binance orders refusedmissing consent (no --wallet, non-interactive, no --yes)pass --wallet <agent> (mandate gate) or run interactively and confirm

Diagnostics ​

SymptomCauseFix
config validate fails on passphraseedited network profilepassphrases must match the canonical values; restore from defaults
doctor exits non-zeroAPI liveness check failedfollow its report; --output json for scripts
keystore errors mention locksconcurrent CLI processesthe write path is atomic + locked; retry — never delete ~/.furlpay to "fix" a lock

FurlPay CLI is non-custodial software. Every execution surface is labeled live or simulated at runtime.