# Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| After signing in, the license page opens instead of the dashboard, or an existing admin session is redirected to the license page | License `SUSPENDED` or `NOT_ACTIVATED` | Restore the existing license's validity with the provider and use **Verify Now**, or enter the key of a new installation in the form on that page. The sign-in itself is not refused: the session reaches the license page, where the reason is shown, and nothing else. |
| License page shows a server warning and hours remaining | License service unreachable (or rate-limiting the host after many restarts) | Check outbound HTTPS. During grace the agent retries in 9–18 minutes and recovers automatically when verification succeeds. The warning appears on the license page and as a banner in the admin topbar on every page. |
| Backups fail — a *Backup Failed* notification (the operator's copy carries the error), a `backup_failed` audit row and the `backup.failed` webhook | Disk pressure on `/var/whost/backups/` | Increase disk or trim retention |
| Plugins page interrupted banner | Activation killed mid-flight | Verify system state, then click "Mark as resolved" |
| OS upgrade stuck at "running" forever | apt lock held by another process | `lsof /var/lib/dpkg/lock-frontend` on the server; resolve and retry |
| 401 on every request after SSH-side config edit | Session secret changed | Re-login and continue |
| Panel opened right after many sign-ins from the same address paints a few seconds late | The edge rate-limits every `/api/v1/auth/*` call per address (12/min) and answered `429` to the shell's session check | Nothing — the shell waits the announced interval and asks again; only a `401`/`403` answer ends the session |

For deeper investigation, `agent.log` (`/var/log/whost/agent.log`) is the canonical place. Released panels ship with the browser debug beacon switched off, so browser-side problems are read from the browser's DevTools (Console and Network tabs).

For the client-facing companion, see [`docs/user/client-user-guide.md`](../user/client-user-guide.md). For HMAC-only API usage, see [`docs/developer/api-reference.md`](../developer/api-reference.md).