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 -f docker-compose.selfhosted.yml logs tenant-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 the host can’t reach the GridNMS platform outbound over HTTPS. Check Platform connection on the Service Management page for its current status, or docker compose -f docker-compose.selfhosted.yml logs tenant-server for connection errors.

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

A collector runs directly on its host, so it normally sees the real sending-device IP with nothing to configure. If a source IP still looks wrong, check whether something upstream of the collector (a relay, load balancer, or NAT device) is rewriting it before the packet arrives, and rely on GridNMS’s Sender Host attribution (extracted from the log payload) in the meantime. 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 -f docker-compose.selfhosted.yml logs tenant-server.

Support: support@gridnms.io or your customer portal.