Troubleshooting

Install & startup

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).

Licensing

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.

Passkeys

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.

Updates

Symptom	Check
Updater not applying a release	That’s the default — updates are notify-only until you opt in with UPDATER_AUTO_APPLY=1. Run docker logs gridnms-updater to see pending releases. See Updates.

Syslog / SNMP traps show the wrong source IP

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.

Getting help

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.