| Symptom |
Check |
| Compose won’t start, complains about a variable |
A required .env secret is unset. Re-run the installer or fill it in — see Configuration. |
| UI loads but the API errors |
docker compose logs server — DB, secret, and license issues log here. |
| Need to start over |
docker compose -f docker-compose.selfhosted.yml down -v wipes volumes (destructive). |
| Symptom |
Check |
License stuck at UNLICENSED |
Wrong/typo’d GRIDNMS_LICENSE_KEY, or no outbound 443 to platform.gridnms.io. Run docker compose logs server | grep cloud-connector. |
| Symptom |
Check |
| Passkey enrollment fails |
The access URL must match what’s in the browser. Fix APP_URL in .env and re-run. Password login works regardless. |
| Locked out — forgot password, lost passkey, or wrong/missing email |
On a self-hosted instance, run the recovery script: Reset an Admin Password. On Cloud, use the login-screen reset link or contact support. |
| Symptom |
Check |
| Updater not updating |
R2_* unset (updates disabled) or no outbound to images.gridnms.io. Run docker compose logs updater. See Updates. |
This is almost always a Docker NAT issue, not a GridNMS bug. On Docker bridge
networking — and always on Docker Desktop for Mac/Windows — the packet source is
rewritten to the docker gateway. Run the collector with host networking on Linux,
use the native desktop app, or rely on GridNMS’s Sender Host attribution
(extracted from the log payload). Full details in
Getting the real source IP.
When contacting support, attach install.log (written next to the installer) and
the output of docker compose logs server.
Support: support@gridnms.io or your customer portal.
