> For the complete documentation index, see [llms.txt](https://docs.netauthpay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.netauthpay.com/deployment/troubleshooting.md).

# 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.

***
