Skip to content

Troubleshooting

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

Section titled “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.

Symptom Check
A device you monitor stays Unknown and never reports as seen The collector covering it has the Monitor service switched off, so nothing pings it. The device’s own page names the collector and links to its settings — see Collector Services. Every service on a newly enrolled collector starts off.
Metrics never appear for a device The covering collector needs the Poller service on, and the device needs working credentials. Open the device’s Actions tab and poll it on demand to see the error.
A device’s Logs tab is empty, but the Logs page finds its messages The name the host writes into its own messages is not one of the names recorded on the device. Add it as the device’s DNS name — see Logs on a device page.
A host’s performance metrics or GPUs never appear on its device Its Log Forwarder is not linked to the device. The Forwarders tab shows the link and lets you make it by hand — see Linking a forwarder to a device.

Is the log service up? Reading the About window

Section titled “Is the log service up? Reading the About window”

Administrators can check the log service from the user menu: choose About, then look at Log server under Backend components. The same line is included when you choose Copy support info. It has three readings:

You see What it means
A version number, with a build in brackets The log service answered and reported its version and build.
reachable, with no version The log service is up and serving, but it was too busy to report its version and build just now. This is the case to understand: it is not an outage. Logs keep arriving and searches keep working. Open About again in a minute and the version returns once the load eases. If it stays this way for long periods, the host running the log service is short of capacity.
unreachable The log service did not answer at all. Check that it is running and that the server can reach it; on a self-hosted install, see the Install & startup checks above.

Earlier releases showed unreachable whenever the log service was merely slow to report, so a busy but healthy service could read as down about half the time. If you saw that, the log service was not necessarily down.

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.

docs built 2026-11-12 · 945a2dec2