# Common issues

> Fix the frequent failure modes fast: a server that shows offline, firewall metrics that stop appearing, and the exact error messages the console returns.
>
> Canonical: https://xdp.network/docs/troubleshooting/common-issues · Updated 2026-08-17

Match your symptom to a section below and work through the checks in order. Most
problems come down to the fleet daemon on the server, the metrics key saved in the
console, or network reachability between the two.

## Server shows offline

A fleet server shows offline when its daemon hasn't checked in for over two minutes —
the daemon (`xdpd`) normally reports every ~15 seconds, and an offline server's health
score is capped at 50. Work through these in order:

1. **Check the daemon on the box.** Run `systemctl status xdpd` on the server. If the
   service is stopped or failed, start it there — nothing in the console can reach a
   dead daemon.
2. **Check outbound connectivity.** The daemon polls the console over HTTPS, so the
   server needs outbound access to it. A firewall or DNS regression on the box looks
   exactly like a daemon crash from the dashboard.
3. **Restart a live-but-stuck daemon from the console.** On the server's **Products**
   tab, under **Server actions**, **Restart** cycles the `xdpd` service; reporting
   resumes within ~30 seconds. Queued actions only run when the daemon checks in, so
   this helps a flaky daemon, not a stopped one.
4. **Re-enroll when the enrollment itself is broken.** Also under **Server actions**,
   **Re-enroll** mints a fresh single-use enroll command — use it after wiping the
   daemon config or moving the box. Run the command on the server as root; the token
   expires shortly after and is never shown again. The current enrollment keeps
   working until the command runs, so minting one is safe.

If the server still shows offline after all four, open a ticket with the server label,
the output of `systemctl status xdpd`, and when the box was last reachable.

## Firewall metrics not appearing

The OpenShield-XDP product console polls the agent's metrics API on your server with a
stored `osk_…` key. The failure mode tells you which side to fix:

- **`invalid API key (401)`** — the key saved in the console no longer matches the
  agent. Run `openshield key` on the server to print the current key, then update the
  saved one with **Rotate key** in the server row's menu on the product page.
- **`this dashboard's IP is not in the server's metrics whitelist (403)`** — the key is
  valid but the console's egress IP is outside `metrics.whitelist` in
  `/etc/openshield/openshield.yaml`. Add a covering CIDR, then `openshield reload`.
- **Timeout after 20 seconds** — the server is offline, blocking the console's IPs, or
  busy applying a large geo/feed update. If timeouts persist, set
  `auto_fetch.mode: 'dedicated'` and confirm the metrics port is reachable.
- **`502`** — the console's metrics proxy couldn't get an answer from the agent. Check
  the agent on the server with `openshield status`, then `openshield reload` if the
  config changed.

If the server row is healthy but some panels are empty, the agent is omitting those
sections: make sure `metrics.enabled: true` is set, run `openshield reload` after every
config edit, and update the agent if it predates the panel — older agents simply don't
send newer sections. If a teammate sees data you don't, your account lacks the
analytics grant — ask an admin; nothing on the server needs to change.

## Common error messages

Match the message verbatim, then apply the fix. The **Test connection** button reports
`ok`, `invalid API key (401)`, `source IP not allowed (403)`, `server returned
<status>`, or `unreachable` — the same fixes apply.

| Message | Meaning | Fix |
| --- | --- | --- |
| `invalid API key (401) — check the key on the server with: openshield key` | Saved metrics key doesn't match the agent | Rotate the key (above) |
| `this dashboard's IP is not in the server's metrics whitelist (403)` | Console IP outside `metrics.whitelist` | Add a covering CIDR, `openshield reload` |
| `server returned <status>` | The agent answered with an unexpected status | `openshield status` on the server; reload if the config changed |
| `forbidden: analytics access required` (403) | Your account lacks the analytics grant for this server | Ask an admin to grant access |
| `unknown control path` (400) | The control proxy asked for a path the agent doesn't recognize — typically an older agent | Update the agent |

On the public [REST API](/docs/reference/api), the three failures to know are `401`
(missing, revoked, or disabled-account token), `404` (unknown id — or a resource owned
by someone else, by design), and `429` (over the 120 requests/minute per-token limit;
wait the `Retry-After` seconds).

## Open a ticket

When every check passes and the problem persists, open a ticket from **My tickets** in
the console sidebar. Copy the error message verbatim — the wording identifies which
component rejected the request — and include the server name as shown in the console.

## Next steps

- [Console REST API](/docs/reference/api)
- [OpenShield-XDP](/docs/products/openshield-xdp)
- [What is XDP.NETWORK](/docs/getting-started/what-is-xdp-network)