# Common errors

> The exact error messages the console and agent produce — 401, 403, timeout, 502, and the permission forbiddens — with meaning and fix.
>
> Canonical: https://xdp.network/docs/troubleshooting/common-errors · Updated 2026-08-09

Match the message you see verbatim, then follow the fix. The console polls the agent's
`GET /metrics` (and `GET /health` for connection tests) with
`Authorization: Bearer osk_…`, so most failures come down to the key, your IP, or
reachability.

## Metrics and connection errors

These come from the metrics API itself, or from the **Test connection** button calling
`/health`.

| Message | Meaning | Fix |
| --- | --- | --- |
| `invalid API key (401) — check the key on the server with: openshield key` | The key saved in the console does not match the agent's key | Run `openshield key` on the server and re-copy the key into the console |
| `this dashboard's IP is not in the server's metrics whitelist (403)` | The console's egress IP is outside `metrics.whitelist` | Add a covering CIDR to `metrics.whitelist`, then `openshield reload` |
| Timeout after 20s | The server is offline, blocks the dashboard's IPs, or is busy applying a large geo/feed update | If it persists, set `auto_fetch.mode: 'dedicated'` and confirm the port is reachable |
| `502` | The metrics proxy is surfacing an agent-side failure | Check the agent with `openshield status`, then `openshield reload` if the config changed |

The test button reports `ok`, `invalid API key (401)`, `source IP not allowed (403)`,
`server returned <status>`, or `unreachable` — the fixes above apply. For a row that
stays red, see [Server shows offline](/docs/troubleshooting/server-shows-offline).

## Permission and control errors

These come from the console's permission checks and the agent's control proxy.

| Message | Meaning | Fix |
| --- | --- | --- |
| `forbidden: analytics access required` | Your account lacks the analytics grant; the server row shows a gray dot | Ask an admin to grant analytics access under **Administration** |
| `unknown control path` (400) | The control proxy asked the agent for a path it does not recognize — typically an older agent | Update the agent; if the message persists, open a ticket |
| `method not allowed` (405) | The control path exists but not for the method used | Retry once from the console; if repeatable, open a ticket |
| `forbidden: <tab> read/edit required` (403) | Your account lacks read or edit permission on that console tab | Ask an admin for the matching grant |

## Errors not listed here

Open a ticket with the exact message and the server name as shown in the console. Copy
the message verbatim — the wording identifies which component rejected the request.

## Next steps

- [API error reference](/docs/api-reference/errors)
- [Server shows offline](/docs/troubleshooting/server-shows-offline)
- [Connecting a server to the dashboard](/docs/openshield-xdp/connecting-a-server)