Troubleshooting

"ENCRYPTION_KEY must be set"

• Set ENCRYPTION_KEY in your environment or .env.

• Required for any flow that creates wallets or sends payments.

• The CLI can still show --help without it (services load lazily).

"Wallet not found" / "Agent not found"

• Ensure the agent was registered first (POST /api/agents/register or netauth agent register <id>).

• If the server restarts and you use in-memory storage, all agents and wallets are lost; re-register or move to persistent storage.

"Insufficient balance"

• The sender’s Solana wallet does not have enough lamports.

• Fund the wallet (e.g. via airdrop on devnet or a transfer from another wallet) or reduce the payment amount.

Payment stuck in "pending" or "processing"

• Payments are processed asynchronously. Wait a few seconds and check again.

• If the server crashed or the Solana RPC failed, the payment may stay in processing or fail; check server logs and RPC health.

• Query GET /api/payments/:paymentId?agentId=... to see current status and transaction signature (if completed).

x402 warnings in logs

• If X402_ENDPOINT or X402_API_KEY is not set, the system uses a local privacy-token fallback.

• Payments still work; only external x402 features are disabled. Configure x402 when you need the full protocol.

CLI returns 404 or connection refused

• Ensure the NetAuth server is running and reachable.

• If using the CLI against a remote server, set the base URL in your client (e.g. via a wrapper or env) or use the API directly with the correct base URL.

Pagination: wrong total or missing payments

• With in-memory storage, data is lost on restart.

• total reflects the current in-memory count; if you use filters (status), total is the count of matching payments before pagination.

---