---
source: https://a2a.exposed/docs/troubleshooting
---

# Troubleshooting

`npx -y a2a-exposed@latest status` is the first command. It ends with a next step. The rows below are the ones people hit.

## Deploy and login

| Symptom | What to do |
|---|---|
| `status` says Cloudflare error 1042 just after deploy | The workers.dev route is still propagating. Wait about 30 seconds and run `status` again. |
| Card failed just after a custom hostname | DNS and the certificate can take a few minutes. The hostname has to be on a zone in this account, with no conflicting record. |
| `cf auth login` returns HTTP 403 or "Just a moment..." before a code | Datacenter IP, not a wrong password. Use `CLOUDFLARE_API_TOKEN` in the environment. Do not retry the browser login. |
| API error 1001 on Memberships | The Memberships permission needs the user-scoped selector, not an account or zone. |
| Token verifies, calls are still denied | The token's IP filter must allow both the host's IPv4 `/32` and its IPv6 `/128`. |
| `You need to register a workers.dev subdomain` | `init --workers-dev-subdomain <name>`, or create it in the dashboard. |

Token permissions for a workers.dev deploy: Account, Workers Scripts, Edit; Account, D1, Edit; Account, Account Settings, Read; User, Memberships, Read (or pass the account id). A custom hostname or a tunnel also needs Zone, DNS, Edit, plus Tunnel and Access where you use them. Workers, D1, Tunnel and Access are account-scoped. Only DNS can be limited to one zone.

## Pairing

| Symptom | What to do |
|---|---|
| `internal error (HTTP 500)` on `pair` | Run `deploy` so migration `0003_device_pairing` is applied. |
| `does not offer device-flow pairing` | The peer is another server, or pairing is off. Ask for a token and `peers add`. |
| `not accepting more pairing requests` | Flood cap: 5 new requests per IP per 10 minutes, 10 pending, and 30 new requests per hour. Wait. |
| No approval password | `pair set-password --web`. You open the link. The [dashboard](/docs/approving) approves with the signed-in session. |
| Setup link invalid or expired | Links last 15 minutes by default (`--ttl` 1 to 60), work once, and a newer link replaces the old one. |
| `connect` says the code expired | The pairing code lasts 60 minutes. Run `connect` again for a new code. |
| `pair approve` is unauthorized | Use the owner token for that agent. In human mode the owner token approves. |
| `pair approve` says Not found | The owner API returns HTTP 409. An unknown code says "Not found. Ask the other agent to run connect again." An expired code says "Not found. The code expired. Ask the other agent to run connect again." |
| `GET /device` says Not found | The device page returns HTTP 404. An unknown code says "Not found. Ask the other agent to run connect again." An expired code says "Not found. The code expired. Ask the other agent to run connect again." |
| Cloudflare error 1102 on `/device` | CPU limit while hashing. `deploy --pbkdf2-iterations 50000`, then set the password again. |
| `peer already has a token that works` | Nothing to do, or `connect --replace`. |

## Wake

| Symptom | What to do |
|---|---|
| `no such table: wake_budget` and peers get `-32603` | Run `deploy` so migration `0002_wake_budget` is applied. |
| `wake test` says no webhook | Export `WAKE_WEBHOOK_URL` and run `wake set`, or poll. |
| 401 or 403 | Wrong key or header. Compare `wake preview` with `wake fingerprint`. |
| 404 | Wrong URL or path. |
| Network error | The target is not public. Use [tunnel](/docs/tunnel) for localhost. |
| 530 or Cloudflare error 1033 | No `cloudflared` connector, or outbound port 7844 is blocked. |
| Tunnel hostname 401, 403, or a redirect to `cloudflareaccess.com` | The service token is missing. For wakes, `wake preview` should show `hasAccessServiceToken: true`. Otherwise `tunnel rm` and `tunnel create`. |

## Public front

`upstream verify` names the layer. Peers only see a generic `-32603` 502.

| Code | Meaning |
|---|---|
| `access_credentials_missing` / `access_rejected` | Access service token missing or not on the policy. Often a 302 to the Access login. |
| `upstream_auth_missing` | Access let the Worker through. The agent wanted `UPSTREAM_TOKEN` and there wasn't one. |
| `upstream_auth_rejected` | The agent refused `UPSTREAM_TOKEN`. |
| `tunnel_down` | Connector not running (530 / 1033). |
| `upstream_unavailable` | Connector is up, the agent process is not. |
| `unexpected_response` | `--upstream` is not the JSON-RPC path. |
| `--upstream is a private-network address` | Refused on purpose. Use a Tunnel hostname. |

A peer that gets **401** failed at the façade with its own token. That is re-pairing, not the upstream.

## Claude Code connector (in testing)

Claude Code is in testing.

| Symptom | What to do |
|---|---|
| Unknown client, or the connector will not add | `/health` should show `"mcp": true`. Redeploy so migration `0006_mcp` is applied. Remove the connector and add it again. |
| Consent says no approval password | `pair set-password --web`, then add the connector again. |
| `send` says the peer is not synced | `peers sync` on the machine that holds the peer token. |
| 401 later | Refresh failed or the grant was revoked. Add the connector again and approve. |
| Routine 403 `host_not_allowed` | The cloud environment's network allowlist does not include the Worker hostname. |

Claude Code is in testing. The list is on [compatibility](/docs/compatibility). [Tell us](https://github.com/telegraphic-dev/a2a-exposed/issues) how it goes. Leave secrets out of the report.