What causes "Error creating SNMP session: ${error.message}" in louislam/uptime-kuma?

Verify network reachability of the agent host and that UDP port 161 (or the configured monitor.port) is open and not blocked by a firewall.

louislam/uptime-kuma · error · Error

Error creating SNMP session: ${error.message}

Error message

Error creating SNMP session: ${error.message}

What it means

Thrown from the 'error' event handler registered on a net-snmp Session/V3Session. net-snmp emits 'error' when the underlying UDP socket experiences an asynchronous failure that is not tied to a specific in-flight request (e.g. socket bind error, EACCES, ENETUNREACH on send). The handler stringifies error.message into a new Error and re-throws it. Note: because this fires inside an EventEmitter callback, the throw does NOT reject the awaited session.get() Promise on line 42 — it surfaces as an uncaught exception, so the surrounding monitor run is terminated abnormally.

Source

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

            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}`);
            });

            const varbinds = await new Promise((resolve, reject) => {
                session.get([monitor.snmpOid], (error, varbinds) => {
                    error ? reject(error) : resolve(varbinds);
                });
            });
            log.debug(
                this.name,
                `SNMP: Received varbinds (Type: ${snmp.ObjectType[varbinds[0].type]} Value: ${varbinds[0].value})`
            );

            if (varbinds.length === 0) {
                throw new Error(`No varbinds returned from SNMP session (OID: ${monitor.snmpOid})`);
            }

            if (varbinds[0].type === snmp.ObjectType.NoSuchInstance) {
                throw new Error(`The SNMP query returned that no instance exists for OID ${monitor.snmpOid}`);

View on GitHub (pinned to 6b5ea01557)

Solutions

Verify network reachability of the agent host and that UDP port 161 (or the configured monitor.port) is open and not blocked by a firewall.
Confirm the Uptime-Kuma process has permission to open UDP sockets on the chosen port and that no other process is squatting on it.
If using SNMPv3, ensure the username and securityLevel (noAuthNoPriv) are accepted by the agent; capture a packet trace to see if the agent returns an SNMP report error.
Refactor the handler so socket errors reject the active request: instead of 'throw' inside session.on('error'), store the error and reject the pending Promise, or attach the handler inside the Promise executor where reject is in scope.

Example fix

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

// after — wire the socket error to the in-flight request so the throw actually rejects
const varbinds = await new Promise((resolve, reject) => {
    session.get([monitor.snmpOid], (error, varbinds) => {
        error ? reject(error) : resolve(varbinds);
    });
});

Defensive patterns

Strategy: try-catch

Validate before calling

// Before creating the session, sanity-check reachability so socket errors surface early.
const { promisify } = require("util");
const dnsLookup = promisify(require("dns").lookup);
async function preflightSnmp(host) {
  try { await dnsLookup(host); }
  catch (e) { throw new Error(`SNMP host unreachable: ${e.message}`); }
}

Type guard

function isSnmpSession(obj) {
  return obj && typeof obj.get === "function" && typeof obj.on === "function" && typeof obj.close === "function";
}

Try / catch

// Wrap the whole get in a single Promise and reject on BOTH the callback error and the socket 'error' event.
const varbinds = await new Promise((resolve, reject) => {
  const onError = (err) => reject(err);
  session.on("error", onError);
  session.get([monitor.snmpOid], (error, vbs) => {
    session.off("error", onError);
    error ? reject(error) : resolve(vbs);
  });
});

Prevention

Validate agent hostname reachability before creating the session.
Always attach the 'error' listener before performing the first request so no socket error is ever unhandled.
Wire socket errors to the in-flight Promise instead of throwing inside the EventEmitter callback.

When it happens

Trigger: Triggered when snmp.createSession/createV3Session succeeds in returning a session object but the underlying dgram socket later emits 'error'. Common causes: binding to a restricted/invalid source port, sending on a down interface, UDP ICMP port-unreachable from the agent (ECONNREFUSED), or a malformed transport error raised by net-snmp internals after construction.

Common situations: Misconfigured SNMP port (e.g. port already bound), agent host unreachable at the IP layer after the session was created, SNMPv3 session created with a username but the agent actively rejects, or running under a user without raw/datagram socket privileges. Also seen when the session object is reused after close().

Related errors

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