{"record":{"id":"6e0320f3b4b772c3","repo":"openai/codex","slug":"connection-failed-0","errorCode":null,"errorMessage":"connection failed: {0}","messagePattern":"connection failed: (.+?)","errorType":"exception","errorClass":"TransportError","httpStatus":null,"severity":"error","filePath":"codex-rs/http-client/src/error.s","lineNumber":21,"sourceCode":null,"sourceCodeStart":null,"sourceCodeEnd":null,"githubUrl":"https://github.com/openai/codex/blob/339751715c64496cb86246bfb3935f40e309dd3d/codex-rs/http-client/src/error.s#L21","documentation":"TransportError::Connection wraps a reqwest error for which is_connect() is true; the reqwest error is preserved as #[source] and the request URL is stripped via without_url() (transport.rs:82). It means the transport never completed an HTTP exchange: DNS resolution, TCP connect, or the TLS handshake to the origin or proxy failed. Inspect .source() for the underlying reqwest error details.","triggerScenarios":"HttpTransport::execute/stream fails during send with a reqwest is_connect() error: DNS lookup failure (unknown host), connection refused (server down or wrong port), TLS handshake or certificate failure while connecting, or an unreachable configured proxy.","commonSituations":"Wrong hostname or port in configuration, DNS/hosts-file breakage, firewall blocking egress, corporate proxy required but not configured, self-signed or enterprise CA not installed via the custom-CA path, server temporarily down for deployment.","solutions":["Inspect the preserved source error (error.source() downcast to reqwest::Error) to distinguish DNS vs refused vs TLS failure","Verify host, port, and reachability of the endpoint directly (dig/curl) and through the proxy if one is required","For TLS causes, install the enterprise root CA via the custom-CA transport path (build_reqwest_client_with_custom_ca) instead of disabling verification","Retry with backoff: connection failures are often transient (restarts, port exhaustion)"],"exampleFix":"// before\nmatch transport.execute(req).await {\n    Err(e) => log::error!(\"request failed: {e}\"), // opaque\n    r => r?,\n}\n\n// after: classify using the preserved reqwest source\nif let TransportError::Connection(source) = &error {\n    if source.is_connect() && source.to_string().contains(\"dns error\") { /* host/port config */ }\n}","handlingStrategy":"retry","validationCode":"// Pre-flight DNS check before first use (cheap, caches at the resolver)\nasync fn endpoint_reachable(host: &str, port: u16) -> bool {\n    tokio::net::lookup_host((host, port)).await.is_ok()\n}","typeGuard":"fn is_connection_failure(e: &TransportError) -> bool {\n    matches!(e, TransportError::Connection(_))\n}","tryCatchPattern":"if let TransportError::Connection(source) = &error {\n    let detail = source.to_string();\n    if detail.contains(\"dns error\") { return ConfigError::BadHost(detail); }\n    if detail.contains(\"tls\") || detail.contains(\"certificate\") { return ConfigError::Tls(detail); }\n}\n// otherwise: transient connect failure, retry idempotent requests with backoff","preventionTips":["Validate configured hosts and ports at startup with a resolve probe","Install enterprise CAs through the custom-CA transport instead of skipping verification","Keep a bounded retry with exponential backoff for connect-phase failures","Run synthetic health checks against critical endpoints"],"tags":["network","connection","dns","tls","rust"],"backgroundTag":"connection-refused","analyzedSha":"339751715c64496cb86246bfb3935f40e309dd3d","analyzedAt":"2026-08-25T05:35:09.876Z","schemaVersion":2},"datasetVersion":"2026-08-25T06:17:31.827Z"}