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, 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 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, 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 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. Tell us (opens in a new tab) how it goes. Leave secrets out of the report.