Troubleshooting

First: upgrade

Many errors come from an old CLI talking to a newer wallet service.

npm install -g @fluxa-pay/fluxa-wallet@latest
fluxa-wallet --version

If you use the Agent Skill, update it too: read and install https://fluxapay.xyz/skill.md. Your Agent ID survives both upgrades.

Common problems

Symptom	Cause	Fix
FluxA Agent ID not initialized. Run "init" first.	No Agent ID in the data directory	fluxa-wallet init --name "<agent name>" --client "<client>". See Setup
Commands work on one machine but not another	Credentials are stored per data directory	Copy the data directory, or set AGENT_ID / AGENT_TOKEN, or point FLUXA_DATA_DIR at the right folder
agent_not_linked, or check-wallet says not linked	The user hasn't linked the agent to their wallet	fluxa-wallet link-wallet and send the user the URL
Authentication errors after a long idle period	The login token expired	Usually refreshed automatically. Force it with fluxa-wallet refreshJWT
HTTP 503 from wallet commands	The service is briefly unavailable	Wait and retry. Don't run init again: that creates a new agent
A payment or payout returns an approvalUrl	The user must approve	Send the complete URL as a link, then poll the matching status command
Mandate errors on x402, payout, card …	The mandate isn't approved yet, has expired, or doesn't have enough left	fluxa-wallet mandate-status --id <id>. Create a new mandate if needed
mandate-status --mandate … fails	Wrong flag	Use --id
x402 rejects the payload	Only part of the 402 response was passed	Pass the full 402 response body, including the accepts array
Amount errors	Wrong unit	USDC is atomic (6 decimals), card amounts are USD decimals, linked-card mandates are cents. See Amounts and units

Statuses

Status fields mean one of three things:

• processing — still in progress (this includes anything waiting for the user's approval). Poll again; don't resend the request.
• completed — finished successfully.
• failed (or expired, rejected) — didn't complete. Start a new request if the user still wants it.

Command pages describe the exact values each command returns.

Getting help

Include the command you ran, the full JSON error (with code), the CLI version, and the time it happened. Leave out JWTs, agent tokens, card details and API keys.