SNMPv3 authentication failures: authorizationError and usmStats decoded

SNMPv3 authentication failures surface as authorizationError (errorStatus 16, errorIndex 0) on the manager side, with no indication of which step of the User-based Security Model (USM) state machine failed. The manager reports “auth failed” but not whether the username was unknown, the HMAC digest mismatched, the packet arrived outside the time window, or the engine ID was never discovered.

The agent knows exactly what went wrong. Every SNMPv3 engine maintains six read-only Counter32 statistics under the usmStats subtree (RFC 3414). Each failed inbound packet increments exactly one counter before the agent responds with a Report PDU. Manager-side libraries translate that Report PDU into authorizationError, discarding the counter value that pinpoints the root cause.

What this means

When a manager sends an SNMPv3 request that fails USM validation, the agent increments one of six counters under .1.3.6.1.6.3.15.1.1 and sends a Report PDU containing the specific counter varbind. The counter identity is the diagnostic signal.

usmStatsUnknownUserNames and usmStatsWrongDigests distinguish between “user not recognized” and “user recognized but digest wrong.” This separation matters for diagnosing credential rotation mismatches versus scanning attempts. See the broader SNMP auth failure signal taxonomy in the network monitoring checklist.

Common causes

Quick checks

# Poll all six usmStats counters (requires working credentials)
snmpwalk -v3 -l authPriv -u <user> -A <auth> -X <priv> <host> .1.3.6.1.6.3.15.1.1

# Poll a specific counter (wrongDigests example)
snmpget -v3 -l authPriv -u <user> -A <auth> -X <priv> <host> .1.3.6.1.6.3.15.1.1.5.0

# If credentials are broken, use debug dump to see the Report PDU and its varbind.
# The Report PDU is sent even on failed auth, so you get one round of visibility.
snmpget -v3 -l authPriv -u <user> -A <auth> -X <priv> -d <host> .1.3.6.1.2.1.1.3.0

# Check the agent's snmpEngineID (authNoPriv requires correct auth passphrase;
# if auth is also broken, the -d dump above reveals the engine ID during discovery)
snmpget -v3 -l authNoPriv -u <user> -A <auth> <host> .1.3.6.1.6.3.10.2.1.1.0

# Check snmpEngineTime and snmpEngineBoots (for time-window debugging)
snmpget -v3 -l authNoPriv -u <user> -A <auth> <host> .1.3.6.1.6.3.10.2.1.3.0
snmpget -v3 -l authNoPriv -u <user> -A <auth> <host> .1.3.6.1.6.3.10.2.1.2.0

# Look for authenticationFailure traps (OID .1.3.6.1.6.3.1.1.5.5)
grep "authenticationFailure" /var/log/snmptrapd.log | tail -50

# Verify NTP sync on the collector
ntpq -p

The -d flag on net-snmp tools dumps the raw packet exchange, including the Report PDU. If credentials are completely broken, this is the only way to see which usmStats counter the agent returned. The Report PDU is always sent on failed auth.

How to diagnose it

flowchart TD
    A["authorizationError from manager"] --> B["Dump Report PDU with -d"]
    B --> C{"Which usmStats counter?"}
    C -->|UnsupportedSecLevels| D["Algorithm or secLevel mismatch"]
    C -->|NotInTimeWindows| E["Clock skew over 150s"]
    C -->|UnknownUserNames| F["Username not on agent"]
    C -->|UnknownEngineIDs| G["Discovery not done"]
    C -->|WrongDigests| H["Auth passphrase mismatch"]
    C -->|DecryptionErrors| I["Priv passphrase mismatch"]
    E --> J["Fix NTP on both sides"]
    G --> K["Run discovery round-trip"]
    D --> L["Check algorithm support"]
    F --> M["Add user or fix spelling"]
    H --> N["Retype auth passphrase"]
    I --> O["Retype priv passphrase"]

1. Capture the Report PDU. Run snmpget/snmpwalk with -d (net-snmp). The Report PDU names the specific counter. If you have working credentials for a different user on the same device, poll .1.3.6.1.6.3.15.1.1 directly.

2. Branch on the counter.

   • usmStatsUnknownUserNames: username not in the agent’s usmUserTable. Verify via device CLI (show snmp user on Cisco, equivalent on other platforms). Check for typos, case sensitivity, and whether the user was deleted during a config change.
   • usmStatsWrongDigests: username is correct but the auth passphrase is wrong. Retype it in the monitoring profile. Some platforms (F5 BIG-IP and others) silently break on special characters in passphrases; the agent logs “Authentication failed for <user>” but the manager sees only authorizationError.
   • usmStatsDecryptionErrors: privacy passphrase mismatch or corrupted ciphertext. Retype the priv passphrase.
   • usmStatsUnknownEngineIDs: manager has not discovered the agent’s engine ID. Trigger discovery explicitly. Some libraries cache poorly or discard the discovered ID across sessions.
   • usmStatsNotInTimeWindows: packet arrived outside the 150-second sliding window. Check NTP on both sides. Common after agent reboot before NTP resync.
   • usmStatsUnsupportedSecLevels: requested security level or algorithm not configured for that user. Check whether the agent has disabled MD5, DES, or other deprecated algorithms.

3. Check for library bugs. If credentials are correct but auth still fails, consider known compatibility issues:

   • pysnmp 4.4.9 and 4.4.12 cannot decrypt traps sent with MD5 auth + AES-256 privacy. Other combinations (SHA-256 + AES-256, MD5 + 3DES-EDE) work.
   • net-snmp 5.9.x GH#772: a user configured for auth only incorrectly accepts a noAuthNoPriv request instead of returning usmStatsUnsupportedSecLevels. This masks misconfiguration. Fixed in later 5.9.x point releases.

4. Check for EngineBoots corruption. If an authoritative SNMP engine loses boot-count persistence (NVRAM loss, factory reset without persistent engine ID storage), engineBoots may become invalid, causing persistent time-window failures for all peers. The fix requires restoring persistent storage and reinitializing the engine. No client-side workaround exists.

5. Correlate with the broader signal set. An auth failure burst from a single source IP across many devices indicates scanning, not a credential problem. A single failure from a known management IP after a config change indicates a rotation mismatch. See the SNMP timeouts and retries guide for distinguishing auth failures from transport-layer timeouts.

Metrics and signals to monitor

Fixes

Wrong auth or priv passphrase

Retype the passphrase in the monitoring profile. Hidden whitespace, encoding issues, and special characters are the most common culprits. Some platforms silently break on special characters: the agent logs the failure, but the manager only sees authorizationError. Test with a simple ASCII alphanumeric passphrase first to isolate character-encoding issues before debugging anything else.

Username mismatch

SNMPv3 USM binds a single set of auth and priv credentials to each username per engine. You cannot use the same username with different passwords across two monitoring profiles targeting the same device. Each distinct credential set requires a separate username. If two tools share a username but send different passphrases, both will see intermittent usmStatsWrongDigests.

Missing engine ID discovery

The manager must complete a discovery round-trip before sending authenticated requests. In net-snmp, this happens automatically when you omit the engine ID. Some libraries and commercial NMS platforms require explicit configuration. If discovery succeeds but subsequent requests still fail with usmStatsUnknownEngineIDs, the library may not be caching or reusing the discovered engine ID correctly.

NTP drift

The USM time-window check uses a 150-second sliding window relative to the authoritative engine’s clock. If manager and agent disagree on time by more than 150 seconds, every authenticated request fails regardless of credential correctness. Fix NTP on both sides. Drift here also corrupts flow record joins and syslog event alignment.

Algorithm deprecation

MD5 and DES are effectively obsolete. Modern agent builds (net-snmp 5.9+, SNMP4J 3.x, pysnmp 4.4.9+) prefer SHA-256 auth and AES-128 privacy. Agents that have disabled weak algorithms will increment usmStatsUnsupportedSecLevels when a manager requests MD5 or DES. Standardize credential profiles on SHA-256 + AES-128 unless a specific legacy device requires otherwise.

EngineBoots corruption

If the device lost NVRAM or underwent a factory reset, engineBoots may be corrupted, permanently breaking the time-window check for all peers. This requires restoring persistent engine ID and boot-count storage on the device. There is no client-side workaround.

Prevention

• Standardize algorithms. Use SHA-256 + AES-128 across the fleet. Document exceptions for legacy devices that only support MD5 or DES.
• Monitor all six usmStats counters. Any nonzero value in production is abnormal. Alert on the specific counter, not just a generic “auth failure.”
• NTP on every device and collector. A device that drifts after a reboot will silently break all SNMPv3 polling until NTP resyncs.
• Credential vault with escaping rules. Store SNMPv3 passphrases in a vault. Document which special characters are safe per platform. Test credential changes against a single device before fleet-wide rollout.
• One username per credential set per engine. Do not reuse usernames with different passphrases across monitoring tools targeting the same device.
• Track agent versions and CVEs. Two relevant CVEs:
  • CVE-2025-20352: critical SNMP RCE in Cisco IOS and IOS XE, actively exploited. Fixed in IOS 17.15.4a and later. Restrict SNMP access to trusted management IPs via ACLs.
  • CVE-2025-68615: buffer overflow in net-snmp’s snmptrapd daemon. All versions before the patched release are affected. Upgrade snmptrapd if you run it as a trap receiver.
• Verify discovery works for new devices. Test the full discovery-to-authenticated-poll cycle before adding a device to production monitoring.

How Netdata helps

• The SNMP collector exposes per-device polling success and failure rates. Correlate auth failure spikes with device config changes or credential rotation events.
• Poll the six usmStats counters as custom OIDs. Alert on any nonzero value, with separate routing per counter to distinguish scanning from credential drift.
• Per-second resolution means auth failure bursts from a scanning source are visible immediately.
• Correlate SNMP auth failures with NTP offset metrics on both the collector and monitored devices to catch time-window rejections caused by clock skew.
• Pair SNMP auth failure signals with SNMP polling storm cascade detection to distinguish auth failures from scheduler-induced timeouts.

Related guides

• SNMP poller falling behind: the polling-storm cascade and how to catch it
• SNMP timeouts and retries: why devices show as down when they aren’t
• Network monitoring checklist: the signals every production network needs