{"record":{"id":"05732e5a9a00f7fb","repo":"transact-rs/sqlx","slug":"hostname-did-not-resolve-to-any-addresses","errorCode":null,"errorMessage":"Hostname did not resolve to any addresses","messagePattern":"Hostname did not resolve to any addresses","errorType":"exception","errorClass":"io::Error (AddrNotAvailable)","httpStatus":null,"severity":"error","filePath":"sqlx-core/src/net/socket/mod.rs","lineNumber":249,"sourceCode":"\n    let mut last_err = None;\n\n    // Loop through all the Socket Addresses that the hostname resolves to\n    for socket_addr in addresses {\n        match Async::<TcpStream>::connect(socket_addr).await {\n            Ok(stream) => {\n                stream.get_ref().set_nodelay(true)?;\n                return Ok(stream);\n            }\n            Err(e) => last_err = Some(e),\n        }\n    }\n\n    // If we reach this point, it means we failed to connect to any of the addresses.\n    // Return the last error we encountered, or a custom error if the hostname didn't resolve to any address.\n    Err(last_err\n        .unwrap_or_else(|| {\n            io::Error::new(\n                io::ErrorKind::AddrNotAvailable,\n                \"Hostname did not resolve to any addresses\",\n            )\n        })\n        .into())\n}\n\n/// Connect a Unix Domain Socket at the given path.\n///\n/// Returns an error if Unix Domain Sockets are not supported on this platform.\npub async fn connect_uds<P: AsRef<Path>, Ws: WithSocket>(\n    path: P,\n    with_socket: Ws,\n) -> crate::Result<Ws::Output> {\n    #[cfg(unix)]\n    {\n        #[cfg(feature = \"_rt-tokio\")]\n        if crate::rt::rt_tokio::available() {","sourceCodeStart":231,"sourceCodeEnd":267,"githubUrl":"https://github.com/transact-rs/sqlx/blob/03af8bcc5711a1935580a54bea249c219a0c217d/sqlx-core/src/net/socket/mod.rs#L231-L267","documentation":"When opening a TCP connection, sqlx resolves the hostname and tries each returned address. If resolution returns zero addresses (or none succeeded and no error was recorded), it produces `AddrNotAvailable` with 'Hostname did not resolve to any addresses'. This signals DNS resolution produced nothing usable.","triggerScenarios":"`connect_tcp_async_io` (or the tokio variant) called with a host string that fails DNS resolution — empty resolve result — e.g. `connect options with host = 'db.internal'` where DNS returns no records.","commonSituations":"Typo in the database host in DATABASE_URL/config; DNS outage or misconfigured resolv.conf; hostname only resolvable inside a container/VPN network; IPv6-only or IPv4-only resolution mismatch.","solutions":["Verify the hostname resolves: `nslookup <host>` / `dig <host>` from the same machine","Fix the host in your connection string/environment (DATABASE_URL, config file)","Ensure the client runs on a network (or VPN/container DNS) that can resolve the DB hostname","As a workaround, connect by resolved IP address to rule out DNS"],"exampleFix":"// before\nlet opts = PgConnectOptions::new().host(\"db.internal\");\n// after: confirm DNS first, or use a resolvable host/IP\nlet opts = PgConnectOptions::new().host(\"10.0.2.15\"); // or correct hostname","handlingStrategy":"validation","validationCode":"// before connecting\nlet resolved = tokio::net::lookup_host((host.as_str(), port)).await;\nif resolved.is_err() || resolved.unwrap().next().is_none() {\n    eprintln!(\"host {host} does not resolve\");\n}","typeGuard":null,"tryCatchPattern":"match pool.connect().await {\n    Err(e) if e.to_string().contains(\"did not resolve to any addresses\") => {\n        // surface config problem to user; do not blindly retry\n    }\n    other => other?,\n}","preventionTips":["Validate the DB host resolves in CI/health checks before deploy","Avoid hardcoding internal hostnames usable only inside specific networks","Prefer IP or verified DNS names in config; document VPN/container DNS requirements"],"tags":["rust","sqlx","dns","network","hostname","tcp"],"backgroundTag":"dns-resolution-failed","analyzedSha":"03af8bcc5711a1935580a54bea249c219a0c217d","analyzedAt":"2026-09-03T15:01:28.752Z","contentChangedAt":"2026-09-03T15:01:28.752Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}