# Server shows offline

> Diagnose a red offline dot: agent stopped, metrics disabled, wrong URL or port, a whitelist that misses the console, or a bad key.
>
> Canonical: https://xdp.network/docs/troubleshooting/server-shows-offline · Updated 2026-08-09

A red offline dot means the console's poll of your agent's metrics API is failing. Work
through the checks in order — each one names the command or error that decides whether
you move on.

## Run the checks in order

1. **Check the agent is running.** On the server, run `systemctl status openshield` and
   `openshield status`. If the unit is stopped, nothing can answer the console — bring
   the agent up first.

2. **Check metrics are enabled and reloaded.** `metrics.enabled` must be `true` in
   `/etc/openshield/openshield.yaml`, and the console only sees the running config — run
   `openshield reload` after every edit. See [Enabling metrics](/docs/openshield-xdp/enabling-metrics).

3. **Check the URL and port.** The Metrics API URL saved in the console must match
   `metrics.listen` (host:port), and that port must be listening and reachable from
   outside. `openshield key` prints the exact URL and key the agent expects.

4. **Check the whitelist covers the console.** A 403 means "this dashboard's IP is not
   in the server's metrics whitelist (403)". Add a CIDR to `metrics.whitelist` that
   covers the console's egress IP, then `openshield reload`.

5. **Check the key.** A 401 means "invalid API key (401) — check the key on the server
   with: openshield key". Re-copy the key into the console and save. 401 is the key;
   403 is your IP — do not mix up the fixes.

6. **Rule out slow responses.** A timeout (20s) means the server is offline, is blocking
   the dashboard's IPs, or is busy applying a large geo/feed update. If timeouts persist,
   set `auto_fetch.mode: 'dedicated'` and confirm the port is reachable.

:::note
Read the dot carefully: red is offline, amber "under attack" means an attack is active
(see [During an attack](/docs/attack-mitigation/during-an-attack)), and gray means you
lack analytics permission (see [Metrics not appearing](/docs/troubleshooting/metrics-not-appearing)).
A 502 means the metrics proxy is surfacing an agent-side failure.
:::

## Open a ticket if every check passes

If the row is still red, open a ticket and include the server name as shown in the
console, the exact error the dashboard reports (401, 403, timeout, or 502), the output
of `openshield status` and `openshield key`, and the `metrics.listen` and
`metrics.whitelist` lines from your config.

## Next steps

- [Metrics not appearing](/docs/troubleshooting/metrics-not-appearing)
- [Common errors](/docs/troubleshooting/common-errors)
- [Connecting a server to the dashboard](/docs/openshield-xdp/connecting-a-server)