Troubleshooting

If something fails, run with --verbose first — it surfaces the tracing event that triggered the error.

pay --verbose --sandbox curl <url>

Payment rejected by verifier

Cause: the verifier server received your signed challenge but refused it. The error message includes the verifier's reason.

Fix:

• If the reason includes (retryable — try again), re-run the same command. The verifier may have caught a transient signature mismatch.
• If not retryable, the request URL, headers, or body changed between the challenge and your signed retry. Make sure nothing is rewriting the request mid-flight (proxies, interceptors). Use pay --debugger to capture the full exchange.

Server returned 402 again after payment

Cause: payment succeeded on-chain but the server didn't accept the signed credential.

Fix:

• Check the server's clock and clock-skew tolerance.
• Re-run with pay --debugger so the PDB UI captures the second 402 — it shows what the server expected versus what your client sent.

No MPP challenge matched the active network filter

Cause: you passed --mainnet or --sandbox but the server only advertised challenges on the other network.

Fix: drop the network flag and let pay follow the challenge, or run pay account list to confirm you have an account on the offered network.

The automatic payment cap is stablecoin-denominated and cannot price <currency> payments automatically

Cause: you set --yolo-upto <cap> but the challenge advertised a non-stablecoin currency (e.g. SOL).

Fix: drop --yolo-upto and approve the payment interactively, or restrict the gateway/provider to stablecoin endpoints.

pay setup doesn't write an MCP config for my agent

Cause: the agent's config directory wasn't found at the time of install, or the file already exists.

Fix: re-run with --update after launching the agent at least once:

pay setup --update

account locked / OS keychain prompt loops on every call

Cause: the keychain backend requires per-call auth and your account has auth_required: true.

Fix: for sandbox or low-stakes accounts, edit ~/.config/pay/accounts.yml and set auth_required: false on the entry. Mainnet accounts should stay locked; see Configuration for the schema.

Address already in use on port 1402

Cause: another process — usually a prior pay --debugger or pay server — held the port.

Fix:

lsof -i :1402

Kill the process, or bind elsewhere: pay server start spec.yml --bind 0.0.0.0:1403.

Sandbox calls hang on first run

Cause: the Surfpool sandbox is fetching and funding your ephemeral wallet on first use. This takes a few seconds.

Fix: wait. Subsequent calls reuse the same wallet (under localnet: in accounts.yml) and skip the bootstrap.

More

• pay --help — the full command tree, grouped.
• GitHub issues — search before filing.