Tencent/WeKnora · error

failed to connect to validated addresses for

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.

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

• DNS resolution failed for
• DNS resolution returned no addresses for
• download zip
• failed to execute Exa request
• failed to execute Metaso request

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

Appendix: 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)