{"record":{"id":"006ce6440ee03ca7","repo":"louislam/uptime-kuma","slug":"connection-failed","errorCode":null,"errorMessage":"Connection failed","messagePattern":"Connection failed","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"server/monitor-types/tcp.js","lineNumber":132,"sourceCode":"\n        // Standard TCP check\n        await this.checkTcp(monitor, heartbeat);\n    }\n\n    /**\n     * Standard TCP connectivity check\n     * @param {object} monitor Monitor object\n     * @param {object} heartbeat Heartbeat object\n     * @returns {Promise<void>}\n     */\n    async checkTcp(monitor, heartbeat) {\n        try {\n            const resp = await tcping(monitor.hostname, monitor.port);\n            heartbeat.ping = resp;\n            heartbeat.msg = `${resp} ms`;\n            heartbeat.status = UP;\n        } catch {\n            throw new Error(\"Connection failed\");\n        }\n\n        let socket_;\n\n        // Handle TLS certificate checking for secure/starttls connections\n        if ([\"secure\", \"starttls\"].includes(monitor.smtpSecurity) && monitor.isEnabledExpiryNotification()) {\n            const reuseSocket = monitor.smtpSecurity === \"starttls\" ? await this.performStartTls(monitor) : {};\n            socket_ = reuseSocket.socket;\n            await this.checkTlsCertificate(monitor, reuseSocket);\n        }\n\n        if (socket_ && !socket_.destroyed) {\n            socket_.end();\n        }\n    }\n\n    /**\n     * Perform STARTTLS handshake for various protocols (SMTP, IMAP, XMPP)","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/louislam/uptime-kuma/blob/6b5ea0155793e666666745fb8d6fef1e829543a2/server/monitor-types/tcp.js#L114-L150","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["From the Uptime-Kuma host, run 'nc -zv <hostname> <port>' or 'telnet <hostname> <port>' to reproduce the connection failure.","Verify the service is running and listening on the expected port (ss -tlnp / netstat).","Check firewall/security-group rules allow inbound TCP from the Uptime-Kuma host to the target port.","Confirm the hostname resolves to the correct IP and address family for the target.","Raise the monitor timeout if the service is slow to accept connections."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"const net = require(\"net\");\nfunction probeTcp(host, port, ms = 3000) {\n  return new Promise(resolve => {\n    const s = net.connect({ host, port });\n    s.setTimeout(ms);\n    s.on(\"connect\", () => { s.end(); resolve(true); });\n    s.on(\"timeout\", () => { s.destroy(); resolve(false); });\n    s.on(\"error\", () => resolve(false));\n  });\n}","typeGuard":"function isTcpReachable(r) { return r === true; }","tryCatchPattern":"try { const r = await tcping(monitor.hostname, monitor.port); ... }\ncatch { heartbeat.status = DOWN; heartbeat.msg = \"Connection failed\"; return; }","preventionTips":["Pre-probe host:port with nc/telnet from the Uptime-Kuma host.","Confirm the service is listening and firewalls allow the SYN.","Tune the monitor timeout for slow-to-accept services."],"tags":["tcp","network","connectivity","port"],"backgroundTag":null,"analyzedSha":"6b5ea0155793e666666745fb8d6fef1e829543a2","analyzedAt":"2026-08-12T23:42:12.959Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}