transact-rs/sqlx · error · io::Error (AddrNotAvailable)

Hostname did not resolve to any addresses

Error message

Hostname did not resolve to any addresses

What it means

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.

Source

Thrown at sqlx-core/src/net/socket/mod.rs:249

    let mut last_err = None;

    // Loop through all the Socket Addresses that the hostname resolves to
    for socket_addr in addresses {
        match Async::<TcpStream>::connect(socket_addr).await {
            Ok(stream) => {
                stream.get_ref().set_nodelay(true)?;
                return Ok(stream);
            }
            Err(e) => last_err = Some(e),
        }
    }

    // If we reach this point, it means we failed to connect to any of the addresses.
    // Return the last error we encountered, or a custom error if the hostname didn't resolve to any address.
    Err(last_err
        .unwrap_or_else(|| {
            io::Error::new(
                io::ErrorKind::AddrNotAvailable,
                "Hostname did not resolve to any addresses",
            )
        })
        .into())
}

/// Connect a Unix Domain Socket at the given path.
///
/// Returns an error if Unix Domain Sockets are not supported on this platform.
pub async fn connect_uds<P: AsRef<Path>, Ws: WithSocket>(
    path: P,
    with_socket: Ws,
) -> crate::Result<Ws::Output> {
    #[cfg(unix)]
    {
        #[cfg(feature = "_rt-tokio")]
        if crate::rt::rt_tokio::available() {

View on GitHub (pinned to 03af8bcc57)

Solutions

1. Verify the hostname resolves: `nslookup <host>` / `dig <host>` from the same machine
2. Fix the host in your connection string/environment (DATABASE_URL, config file)
3. Ensure the client runs on a network (or VPN/container DNS) that can resolve the DB hostname
4. As a workaround, connect by resolved IP address to rule out DNS

Example fix

// before
let opts = PgConnectOptions::new().host("db.internal");
// after: confirm DNS first, or use a resolvable host/IP
let opts = PgConnectOptions::new().host("10.0.2.15"); // or correct hostname

// before connecting
let resolved = tokio::net::lookup_host((host.as_str(), port)).await;
if resolved.is_err() || resolved.unwrap().next().is_none() {
    eprintln!("host {host} does not resolve");
}

match pool.connect().await {
    Err(e) if e.to_string().contains("did not resolve to any addresses") => {
        // surface config problem to user; do not blindly retry
    }
    other => other?,
}

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• expected to read {} bytes, got {} bytes at EOF
• unimplemented!()
• Unix domain sockets are not supported on this platform
• absolute paths will only work on the current machine
• paths relative to the current file's directory are not curre

AI-assisted analysis of transact-rs/sqlx@03af8bcc57 (2026-09-03). Data as JSON: /api/errors/05732e5a9a00f7fb. Report an issue: GitHub.