# Troubleshooting

> Common errors and the fix for each.

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

```sh
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`](/docs/toolchain/global-flags#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:

```sh
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](/docs/toolchain/configuration#accounts-yml) 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:**

```sh
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`](/docs/toolchain/commands) — the full command tree, grouped.
- [GitHub issues](https://github.com/solana-foundation/pay/issues) — search before filing.