{"record":{"id":"9da881696f195b39","repo":"louislam/uptime-kuma","slug":"snmpv3-username-is-required","errorCode":null,"errorMessage":"SNMPv3 username is required","messagePattern":"SNMPv3 username is required","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"server/monitor-types/snmp.js","lineNumber":23,"sourceCode":"class SNMPMonitorType extends MonitorType {\n    name = \"snmp\";\n\n    /**\n     * @inheritdoc\n     */\n    async check(monitor, heartbeat, _server) {\n        let session;\n        try {\n            const sessionOptions = {\n                port: monitor.port || \"161\",\n                retries: monitor.maxretries,\n                timeout: monitor.timeout * 1000,\n                version: snmp.Version[monitor.snmpVersion],\n            };\n\n            if (monitor.snmpVersion === \"3\") {\n                if (!monitor.snmp_v3_username) {\n                    throw new Error(\"SNMPv3 username is required\");\n                }\n                // SNMPv3 currently defaults to noAuthNoPriv.\n                // Supporting authNoPriv / authPriv requires additional inputs\n                // (auth/priv protocols, passwords), validation, secure storage,\n                // and database migrations, which is intentionally left for\n                // a follow-up PR to keep this change scoped.\n                sessionOptions.securityLevel = snmp.SecurityLevel.noAuthNoPriv;\n                sessionOptions.username = monitor.snmp_v3_username;\n                session = snmp.createV3Session(monitor.hostname, monitor.snmp_v3_username, sessionOptions);\n            } else {\n                session = snmp.createSession(monitor.hostname, monitor.radiusPassword, sessionOptions);\n            }\n\n            // Handle errors during session creation\n            session.on(\"error\", (error) => {\n                throw new Error(`Error creating SNMP session: ${error.message}`);\n            });\n","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/louislam/uptime-kuma/blob/6b5ea0155793e666666745fb8d6fef1e829543a2/server/monitor-types/snmp.js#L5-L41","documentation":"For SNMPv3 the monitor requires a username (monitor.snmp_v3_username); a falsy value throws before session creation. SNMPv3 is user-based security (USM), so an empty username cannot form a valid security name. This guard runs before createV3Session so the session is never attempted in an invalid state.","triggerScenarios":"monitor.snmpVersion === '3' and monitor.snmp_v3_username is null/undefined/empty-string. The branch at snmp.js:23 throws immediately, before securityLevel/username are set.","commonSituations":"User selected SNMPv3 but left the username blank, a migration null-ed the field, or a frontend bug omitted it. The code comment notes authPriv/authNoPriv are deferred, but username is mandatory even for noAuthNoPriv.","solutions":["Set monitor.snmp_v3_username to the SNMPv3 USM user configured on the device.","Create the v3 user on the target device (e.g. net-snmp: createUser -e ... USM user).","Re-open the monitor and fill the username field for SNMPv3.","If you do not need v3, switch snmpVersion to 1 or 2c and supply a community string instead."],"exampleFix":"// before\nmonitor.snmpVersion = '3';\nmonitor.snmp_v3_username = '';\n// after\nmonitor.snmpVersion = '3';\nmonitor.snmp_v3_username = 'alarmUser';","handlingStrategy":"validation","validationCode":"function validateSnmpV3(monitor) {\n  if (monitor.snmpVersion === '3' && !(monitor.snmp_v3_username && monitor.snmp_v3_username.trim())) {\n    throw new Error('SNMPv3 username is required');\n  }\n}","typeGuard":"function isSnmpV3WithUsername(m) { return m.snmpVersion === '3' && typeof m.snmp_v3_username === 'string' && m.snmp_v3_username.trim().length > 0; }","tryCatchPattern":"try {\n  await snmpMonitor.check(monitor, heartbeat, _server);\n} catch (e) {\n  if (/SNMPv3 username is required/.test(e.message)) {\n    // prompt user to fill the username; do not retry\n  }\n  throw e;\n}","preventionTips":["Make the v3 username field required in the UI when version === 3.","Create the matching USM user on the device before saving the monitor.","Switch to v1/v2c if USM credentials are unavailable."],"tags":["snmp","snmpv3","config","validation"],"backgroundTag":null,"analyzedSha":"6b5ea0155793e666666745fb8d6fef1e829543a2","analyzedAt":"2026-08-12T23:42:12.959Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}