Tencent/WeKnora · error

failed to connect to validated addresses for %s: %w

Error message

failed to connect to validated addresses for %s: %w

What it means

All SSRF checks passed and the dialer tried each validated (pinned) IP in turn, but every dial attempt failed; this error wraps the last dial error (%w). It is a connectivity failure at the network layer — the security gate was cleared, but no validated address would accept the connection. The underlying error is typically connection refused, timeout, or no route to host.

Source

Thrown at internal/utils/security.go:860

		}
	}

	// If we get here, all IPs are safe. Pin the connection to the validated DNS
	// answers; TLS still uses the request hostname for SNI/certificate checks.
	dialer := &net.Dialer{
		Timeout:   30 * time.Second,
		KeepAlive: 30 * time.Second,
	}
	var lastErr error
	for _, ipAddr := range ips {
		pinnedAddr := net.JoinHostPort(ipAddr.IP.String(), port)
		conn, dialErr := dialer.DialContext(ctx, network, pinnedAddr)
		if dialErr == nil {
			return conn, nil
		}
		lastErr = dialErr
	}
	return nil, fmt.Errorf("failed to connect to validated addresses for %s: %w", host, lastErr)
}

// ---------------------------------------------------------------------------
// SSRF Whitelist mechanism
// ---------------------------------------------------------------------------
//
// The environment variable SSRF_WHITELIST accepts a comma-separated list of
// allowed host patterns. Each entry can be:
//   - An exact domain: "example.com"
//   - A wildcard domain: "*.example.com" (matches all subdomains)
//   - An IPv4 address: "203.0.113.5"
//   - An IPv6 address: "2001:db8::1"
//   - A CIDR range (v4 or v6): "10.0.0.0/8", "2001:db8::/32"
//
// Whitelisted entries bypass the normal SSRF checks performed by isSSRFSafeURL.

var (
	// ssrfWhitelistOnce protects the cold-start ENV-only path. Once

View on GitHub (pinned to 988cbb0330)

Solutions

1. Read the wrapped error: if it is connection refused, check the service is running and listening on the port; if timeout/no-route, check firewalls, security groups, and routing.
2. Verify connectivity from the same host (curl/nc to the resolved IP:port) to separate network issues from code issues.
3. Retry with backoff for transient failures (restarts, scaling events) — errors.Unwrap can tell you if it's a timeout.
4. If DNS answers include unreachable families (e.g. AAAA without IPv6 connectivity), fix the DNS records or enable IPv6 routing so a valid pinned address succeeds.

Example fix

// before
conn, err := utils.SSRFSafeDialContext(ctx, "tcp", "api.example.com:443") // service down, all IPs refused

// after
var conn net.Conn
var err error
for attempt := 0; attempt < 3; attempt++ {
    conn, err = utils.SSRFSafeDialContext(ctx, "tcp", "api.example.com:443")
    if err == nil { break }
    time.Sleep(time.Duration(1<<attempt) * 100 * time.Millisecond)
}

// Security checks will pass if the host resolves to public IPs; check service reachability first:
ips, err := net.LookupIP(host)
if err == nil {
    for _, ip := range ips {
        if c, d := net.DialTimeout("tcp", net.JoinHostPort(ip.String(), port), 2*time.Second); d == nil { c.Close(); break }
    }
}

conn, err := utils.SSRFSafeDialContext(ctx, "tcp", addr)
if err != nil && strings.Contains(err.Error(), "failed to connect to validated addresses") {
    var netErr net.Error
    if errors.As(err, &netErr) && netErr.Timeout() {
        // transient: retry with backoff
    }
    return nil, fmt.Errorf("service unreachable on validated IPs for %s: %w", host, err)
}

When it happens

Trigger: Dialing a host whose service is down, firewalled, or listening on a different interface than the resolved IPs advertise; timeouts shorter than the dial timeout; security groups/NACLs blocking the port; SSRFSafeDialContext trying each pinned address and collecting the final failure (as in TestSSRFSafeDialContextRejectsRestrictedPortAtFinalSink's sink path).

Common situations: Service crashed or not yet started on the target host; cloud security group not open for the port; DNS stale — IPs no longer host the service; IPv6 addresses returned but the local network has no IPv6 connectivity, so all pinned attempts fail.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• service unreachable: %w
• fetch failed: %w
• read body failed: %w
• HTTP GET: %w
• download zip: %w

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/c43be868223125e5. Report an issue: GitHub.