louislam/uptime-kuma · warning · Error

Connection failed

Error message

Connection failed

What it means

Thrown by TCPMonitorType.checkTcp() when the tcping() helper rejects. tcping attempts a TCP connection to monitor.hostname:monitor.port and measures round-trip time; if the connection cannot be established the catch block discards the original error and throws a generic 'Connection failed'. This is the canonical DOWN signal for a port monitor.

Source

Thrown at server/monitor-types/tcp.js:132

        // Standard TCP check
        await this.checkTcp(monitor, heartbeat);
    }

    /**
     * Standard TCP connectivity check
     * @param {object} monitor Monitor object
     * @param {object} heartbeat Heartbeat object
     * @returns {Promise<void>}
     */
    async checkTcp(monitor, heartbeat) {
        try {
            const resp = await tcping(monitor.hostname, monitor.port);
            heartbeat.ping = resp;
            heartbeat.msg = `${resp} ms`;
            heartbeat.status = UP;
        } catch {
            throw new Error("Connection failed");
        }

        let socket_;

        // Handle TLS certificate checking for secure/starttls connections
        if (["secure", "starttls"].includes(monitor.smtpSecurity) && monitor.isEnabledExpiryNotification()) {
            const reuseSocket = monitor.smtpSecurity === "starttls" ? await this.performStartTls(monitor) : {};
            socket_ = reuseSocket.socket;
            await this.checkTlsCertificate(monitor, reuseSocket);
        }

        if (socket_ && !socket_.destroyed) {
            socket_.end();
        }
    }

    /**
     * Perform STARTTLS handshake for various protocols (SMTP, IMAP, XMPP)

View on GitHub (pinned to 6b5ea01557)

Solutions

1. From the Uptime-Kuma host, run 'nc -zv <hostname> <port>' or 'telnet <hostname> <port>' to reproduce the connection failure.
2. Verify the service is running and listening on the expected port (ss -tlnp / netstat).
3. Check firewall/security-group rules allow inbound TCP from the Uptime-Kuma host to the target port.
4. Confirm the hostname resolves to the correct IP and address family for the target.
5. Raise the monitor timeout if the service is slow to accept connections.

const net = require("net");
function probeTcp(host, port, ms = 3000) {
  return new Promise(resolve => {
    const s = net.connect({ host, port });
    s.setTimeout(ms);
    s.on("connect", () => { s.end(); resolve(true); });
    s.on("timeout", () => { s.destroy(); resolve(false); });
    s.on("error", () => resolve(false));
  });
}

function isTcpReachable(r) { return r === true; }

try { const r = await tcping(monitor.hostname, monitor.port); ... }
catch { heartbeat.status = DOWN; heartbeat.msg = "Connection failed"; return; }

When it happens

Trigger: Produced whenever the TCP three-way handshake to (hostname, port) fails or times out: connection refused (ECONNREFUSED), host unreachable (EHOSTUNREACH), no route (ENETUNREACH), DNS failure on the hostname, or tcping's internal timeout elapsing.

Common situations: Service on the target port is down; firewall drops the SYN; wrong port number; hostname does not resolve; target migrated to a different port; transient network blip; IPv6-only host queried via IPv4.

Related errors

• Invalid Docker response, is it Docker really a daemon?
• Connection to Docker daemon timed out.
• Packet size must be between ${PING_PACKET_SIZE_MIN} and ${PI
• No Resolver Servers specified. Please specify at least one r
• None of the configured resolver servers could be resolved to

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