docs/npm/device-metrics/troubleshooting.md
The problems below are the ones that actually come up when polling network devices. Each lists the symptom, the likely cause, and the fix.
Symptom. You added the job but the device shows no node, or only a bare interface count with no vendor-specific metrics.
Likely causes and fixes.
snmpget -v2c -c <community> <device> .1.3.6.1.2.1.1.3.0 (sysUpTime). No answer means a firewall, ACL, wrong community/credentials, or wrong port — not a Netdata problem. SNMP is UDP/161 by default.sysObjectID/sysDescr; an unknown model gets only what generic profiles cover. Check the device's sysObjectID and sysDescr, then add a custom profile with a selector matching them under /etc/netdata/go.d/snmp.profiles/ — it applies automatically once the selector matches. If the device reports no sysObjectID at all (rare), name the profiles to apply with manual_profiles. See SNMP Profile Format./etc/netdata/go.d/snmp.profiles/ with a tighter selector, or report the over-broad selector so it can be fixed upstream.Symptom. Metrics arrive intermittently; the device's SNMP timeout/retry rate is climbing.
Likely causes and fixes.
max_repetitions so each bulk walk asks for fewer rows, and/or raise update_every for that device.update_every, every device suffers. Raise update_every, stagger devices, or split them across more hubs — see Sizing and Scaling.max_repetitions so responses stay small.Symptom. The device answers nothing under SNMPv3, or the very first poll is slow.
Likely causes and fixes.
level, auth_proto, priv_proto, and the two keys must match the device's user exactly. authPriv needs both auth and priv set; authNoPriv needs auth only; noAuthNoPriv needs neither. A single mismatch yields silence.Symptom. An interface briefly shows terabit-per-second utilization with no real event.
Cause. A 32-bit octet counter wrapped (it rolls over in roughly 3.4 seconds at 10G line rate) and naive differencing turned the rollover into a fake spike. Netdata reads the 64-bit high-capacity counters (ifHCInOctets) where the device exposes them — these don't wrap at line rate, so the artifact never appears. A persistent fake spike usually means the device is only exposing 32-bit counters for that interface, or the matched profile isn't collecting the HC variant. Confirm the device supports HC counters and that the profile collects them.
Symptom. Netdata flags the device down; it pings fine and serves traffic.
Likely causes and fixes.
vnode_device_down_threshold (3) consecutive failures, but a genuinely flaky path can still trip it. Compare against the ICMP probe: SNMP down while ICMP is up points at the SNMP agent or the walk, not the device being offline.Symptom. Right after a device reload, SNMP is slow or returns little.
Cause. The SNMP agent may take 30–60 seconds to be ready, and the MIB cache is cold. This is expected; it clears within a cycle or two. Counter resets at reboot are handled by Netdata's counter logic — a counter that jumps backward is treated as a reset, not a negative or impossibly large rate, so you won't see a phantom spike.
Symptom. Interfaces and system metrics are there, but a vendor-specific value you expect (a sensor, a license field, a vendor counter) is not.
Cause and fix. The matched profile doesn't declare that OID for your model. Extend the relevant base profile or add a custom one under /etc/netdata/go.d/snmp.profiles/ that collects the OID, following SNMP Profile Format.