louislam/uptime-kuma · error · Error

SNMPv3 username is required

Error message

SNMPv3 username is required

What it means

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.

Source

Thrown at server/monitor-types/snmp.js:23

class SNMPMonitorType extends MonitorType {
    name = "snmp";

    /**
     * @inheritdoc
     */
    async check(monitor, heartbeat, _server) {
        let session;
        try {
            const sessionOptions = {
                port: monitor.port || "161",
                retries: monitor.maxretries,
                timeout: monitor.timeout * 1000,
                version: snmp.Version[monitor.snmpVersion],
            };

            if (monitor.snmpVersion === "3") {
                if (!monitor.snmp_v3_username) {
                    throw new Error("SNMPv3 username is required");
                }
                // SNMPv3 currently defaults to noAuthNoPriv.
                // Supporting authNoPriv / authPriv requires additional inputs
                // (auth/priv protocols, passwords), validation, secure storage,
                // and database migrations, which is intentionally left for
                // a follow-up PR to keep this change scoped.
                sessionOptions.securityLevel = snmp.SecurityLevel.noAuthNoPriv;
                sessionOptions.username = monitor.snmp_v3_username;
                session = snmp.createV3Session(monitor.hostname, monitor.snmp_v3_username, sessionOptions);
            } else {
                session = snmp.createSession(monitor.hostname, monitor.radiusPassword, sessionOptions);
            }

            // Handle errors during session creation
            session.on("error", (error) => {
                throw new Error(`Error creating SNMP session: ${error.message}`);
            });

View on GitHub (pinned to 6b5ea01557)

Solutions

1. Set monitor.snmp_v3_username to the SNMPv3 USM user configured on the device.
2. Create the v3 user on the target device (e.g. net-snmp: createUser -e ... USM user).
3. Re-open the monitor and fill the username field for SNMPv3.
4. If you do not need v3, switch snmpVersion to 1 or 2c and supply a community string instead.

Example fix

// before
monitor.snmpVersion = '3';
monitor.snmp_v3_username = '';
// after
monitor.snmpVersion = '3';
monitor.snmp_v3_username = 'alarmUser';

function validateSnmpV3(monitor) {
  if (monitor.snmpVersion === '3' && !(monitor.snmp_v3_username && monitor.snmp_v3_username.trim())) {
    throw new Error('SNMPv3 username is required');
  }
}

function isSnmpV3WithUsername(m) { return m.snmpVersion === '3' && typeof m.snmp_v3_username === 'string' && m.snmp_v3_username.trim().length > 0; }

try {
  await snmpMonitor.check(monitor, heartbeat, _server);
} catch (e) {
  if (/SNMPv3 username is required/.test(e.message)) {
    // prompt user to fill the username; do not retry
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Interval cannot be less than ${MIN_INTERVAL_SECOND} seconds
• Retry interval cannot be less than ${MIN_INTERVAL_SECOND} se
• Response max length cannot be less than 0
• Response max length cannot be more than ${RESPONSE_BODY_LENG
• Kafka Producer Brokers must be valid JSON: ${e.message}

AI-assisted analysis of louislam/uptime-kuma@6b5ea01557 (2026-08-12). Data as JSON: /api/errors/9da881696f195b39. Report an issue: GitHub.