Common errors
The exact error messages the console and agent produce — 401, 403, timeout, 502, and the permission forbiddens — with meaning and fix.
Last updated
On this page
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.
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.