{"record":{"id":"4d330da1cfece25b","repo":"nats-io/nats-server","slug":"failed-to-connect-to-proxy-v","errorCode":null,"errorMessage":"failed to connect to proxy: %v","messagePattern":"failed to connect to proxy: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/leafnode.go","lineNumber":632,"sourceCode":"\tif s.leafNodeOpts.dialer == nil {\n\t\ts.leafNodeOpts.dialer = natsDialTimeout\n\t}\n}\n\nconst sharedSysAccDelay = 250 * time.Millisecond\n\n// establishHTTPProxyTunnel establishes an HTTP CONNECT tunnel through a proxy server\nfunc establishHTTPProxyTunnel(proxyURL, targetHost string, timeout time.Duration, username, password string) (net.Conn, error) {\n\tproxyAddr, err := url.Parse(proxyURL)\n\tif err != nil {\n\t\t// This should not happen since proxy URL is validated during configuration parsing\n\t\treturn nil, fmt.Errorf(\"unexpected proxy URL parse error (URL was pre-validated): %v\", err)\n\t}\n\n\t// Connect to the proxy server\n\tconn, err := natsDialTimeout(\"tcp\", proxyAddr.Host, timeout)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to connect to proxy: %v\", err)\n\t}\n\n\t// Set deadline for the entire proxy handshake\n\tif err := conn.SetDeadline(time.Now().Add(timeout)); err != nil {\n\t\tconn.Close()\n\t\treturn nil, fmt.Errorf(\"failed to set deadline: %v\", err)\n\t}\n\n\treq := &http.Request{\n\t\tMethod: http.MethodConnect,\n\t\tURL:    &url.URL{Opaque: targetHost}, // Opaque is required for CONNECT\n\t\tHost:   targetHost,\n\t\tHeader: make(http.Header),\n\t}\n\n\t// Add proxy authentication if provided\n\tif username != \"\" && password != \"\" {\n\t\treq.Header.Set(\"Proxy-Authorization\", \"Basic \"+base64.StdEncoding.EncodeToString([]byte(username+\":\"+password)))","sourceCodeStart":614,"sourceCodeEnd":650,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/leafnode.go#L614-L650","documentation":"The TCP connection to the HTTP proxy server failed during leafnode remote connection. natsDialTimeout could not establish a socket to proxyAddr.Host within the configured proxy timeout, so the CONNECT tunnel cannot even begin. The wrapped error carries the underlying OS/network cause (timeout, connection refused, DNS failure).","triggerScenarios":"establishHTTPProxyTunnel dials proxyAddr.Host and gets an error: proxy host unreachable, wrong host/port in proxy_url, proxy down, DNS not resolving, firewall dropping, or timeout too small for a slow network.","commonSituations":"Typos in proxy_url host/port; proxy service not running or listening only on localhost; container/DNS misconfiguration in Kubernetes; corporate firewall blocking the proxy port; proxy timeout set far below actual network latency.","solutions":["Verify the proxy is reachable: nc -vz <proxy-host> <proxy-port> from the NATS server host","Correct proxy_url host/port in the leafnode remote config","Increase the proxy timeout value if latency is the issue","Check DNS resolution and firewall/security-group rules for the proxy port"],"exampleFix":"// before\nproxy {\n  url: \"http://proxy-wrong-host:3128\"\n  timeout: 1s\n}\n// after\nproxy {\n  url: \"http://proxy.internal:3128\"\n  timeout: 10s\n}","handlingStrategy":"retry","validationCode":"conn, err := net.DialTimeout(\"tcp\", host, 3*time.Second)\nif err != nil { return fmt.Errorf(\"proxy %s unreachable before start: %w\", host, err) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"var conn net.Conn\nerr := retry.Do(func() error {\n    c, e := establishHTTPProxyTunnel(purl, target, timeout, user, pass)\n    if e != nil { return e }\n    conn = c\n    return nil\n}, retry.OnRetry(func(n uint, err error) {\n    log.Printf(\"proxy dial attempt %d failed: %v\", n+1, err)\n}))","preventionTips":["Health-check the proxy port before starting the server","Set proxy timeout above worst-case network RTT","Monitor the proxy service; alert on unreachability","Use stable DNS names and check firewall rules for the proxy port"],"tags":["network","proxy","dial","connectivity"],"backgroundTag":"connection-refused","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}