{"record":{"id":"17fc4a65f39ba6cf","repo":"nginx/nginx","slug":"connect-to-v-failed","errorCode":null,"errorMessage":"connect() to %V failed","messagePattern":"connect\\(\\) to %V failed","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/core/ngx_resolver.c","lineNumber":4636,"sourceCode":"                /*\n                 * Linux returns EAGAIN instead of ECONNREFUSED\n                 * for unix sockets if listen queue is full\n                 */\n                || err == NGX_EAGAIN\n#endif\n                || err == NGX_ECONNRESET\n                || err == NGX_ENETDOWN\n                || err == NGX_ENETUNREACH\n                || err == NGX_EHOSTDOWN\n                || err == NGX_EHOSTUNREACH)\n            {\n                level = NGX_LOG_ERR;\n\n            } else {\n                level = NGX_LOG_CRIT;\n            }\n\n            ngx_log_error(level, &rec->log, err, \"connect() to %V failed\",\n                          &rec->server);\n\n            ngx_close_connection(c);\n            rec->tcp = NULL;\n\n            return NGX_ERROR;\n        }\n    }\n\n    if (ngx_add_conn) {\n        if (rc == -1) {\n\n            /* NGX_EINPROGRESS */\n\n            return NGX_AGAIN;\n        }\n\n        ngx_log_debug0(NGX_LOG_DEBUG_EVENT, &rec->log, 0, \"connected\");","sourceCodeStart":4618,"sourceCodeEnd":4654,"githubUrl":"https://github.com/nginx/nginx/blob/3f6f7824d4e2eb1ac37dec76683d525ac0ff521c/src/core/ngx_resolver.c#L4618-L4654","documentation":"connect() to %V failed from ngx_tcp_connect(): the nonblocking TCP connect to the resolver server (name shown via %V) failed immediately. nginx downgrades to ERR for transient network errnos (ECONNRESET, ENETDOWN, ENETUNREACH, EHOSTDOWN, EHOSTUNREACH) and stays CRIT otherwise (e.g. EADDRNOTAVAIL, EAFNOSUPPORT). The connection is closed and the resolver request fails/retries.","triggerScenarios":"TCP DNS fallback (truncated UDP answer) while the resolver server refuses (ECONNREFUSED - port closed, e.g. 127.0.0.1:53 with nothing listening), is unreachable (no route, firewall drop converted to reset), or the address family is unavailable (IPv6 resolver on IPv4-only host, EAFNOSUPPORT).","commonSituations":"Classic: resolver 127.0.0.1 while local DNS cache only listens on TCP for another address, or is stopped. Firewalls that allow UDP/53 but block TCP/53 (so any truncated answer kills resolution). IPv6 resolver addresses pasted from public DNS guides onto IPv4-only VPSes.","solutions":["Check the errno and the %V server printed on the line; ECONNREFUSED -> nothing listening on that host:port","From the nginx host verify TCP DNS works: dig +tcp @<server> example.com","Open TCP/53 in firewalls between nginx and the resolver (UDP-only allowances break truncated answers)","If IPv6 is unavailable on the host, switch resolver to an IPv4 address (or fix IPv6 routing)"],"exampleFix":"# before\nresolver 127.0.0.1:5353 valid=300s;  # nothing listens on 5353/tcp\n\n# after\nresolver 127.0.0.1:53 valid=300s;   # match the actual listening port","handlingStrategy":"retry","validationCode":"# prove TCP/53 reaches the resolver from the nginx host:\n# dig +tcp @<resolver-ip> example.com\n# nc -vz <resolver-ip> 53\n# failure here predicts 'connect() to %V failed' for truncated-answer fallbacks","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Open both UDP/53 and TCP/53 in firewalls to your resolvers - truncation makes TCP mandatory","Keep local resolvers actually listening on the configured port (check with ss -lntup | grep 53)","Include dig +tcp checks in deployment preflight wherever resolver directives are used"],"tags":["resolver","tcp","connect","econnrefused","firewall","dns-truncation"],"backgroundTag":"connection-refused","analyzedSha":"3f6f7824d4e2eb1ac37dec76683d525ac0ff521c","analyzedAt":"2026-08-22T03:09:46.447Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}