What causes "connect() to %V failed" in nginx/nginx?

Check the errno and the %V server printed on the line; ECONNREFUSED -> nothing listening on that host:port

connect() to %V failed

Error message

connect() to %V failed

What it means

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.

Source

Thrown at src/core/ngx_resolver.c:4636

                /*
                 * Linux returns EAGAIN instead of ECONNREFUSED
                 * for unix sockets if listen queue is full
                 */
                || err == NGX_EAGAIN
#endif
                || err == NGX_ECONNRESET
                || err == NGX_ENETDOWN
                || err == NGX_ENETUNREACH
                || err == NGX_EHOSTDOWN
                || err == NGX_EHOSTUNREACH)
            {
                level = NGX_LOG_ERR;

            } else {
                level = NGX_LOG_CRIT;
            }

            ngx_log_error(level, &rec->log, err, "connect() to %V failed",
                          &rec->server);

            ngx_close_connection(c);
            rec->tcp = NULL;

            return NGX_ERROR;
        }
    }

    if (ngx_add_conn) {
        if (rc == -1) {

            /* NGX_EINPROGRESS */

            return NGX_AGAIN;
        }

        ngx_log_debug0(NGX_LOG_DEBUG_EVENT, &rec->log, 0, "connected");

View on GitHub (pinned to 3f6f7824d4)

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)

Example fix

# before
resolver 127.0.0.1:5353 valid=300s;  # nothing listens on 5353/tcp

# after
resolver 127.0.0.1:53 valid=300s;   # match the actual listening port

Defensive patterns

Strategy: retry

Validate before calling

# prove TCP/53 reaches the resolver from the nginx host:
# dig +tcp @<resolver-ip> example.com
# nc -vz <resolver-ip> 53
# failure here predicts 'connect() to %V failed' for truncated-answer fallbacks

Prevention

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

When it happens

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

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

Related errors

AI-assisted analysis of nginx/nginx@3f6f7824d4 (2026-08-22). Data as JSON: /api/errors/17fc4a65f39ba6cf. Report an issue: GitHub.