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

Unix domain sockets are not supported on this platform

Error message

Unix domain sockets are not supported on this platform

What it means

`connect_uds` connects to a Unix domain socket path. On platforms compiled without Unix socket support (`#[cfg(not(unix))]`), it returns an `io::ErrorKind::Unsupported` error wrapped by sqlx. The library does not emulate UDS on non-Unix platforms.

Source

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

        cfg_if! {
            if #[cfg(feature = "_rt-async-io")] {
                use async_io::Async;
                use std::os::unix::net::UnixStream;

                let stream = Async::<UnixStream>::connect(path).await?;

                Ok(with_socket.with_socket(stream).await)
            } else {
                crate::rt::missing_rt((path, with_socket))
            }
        }
    }

    #[cfg(not(unix))]
    {
        drop((path, with_socket));

        Err(io::Error::new(
            io::ErrorKind::Unsupported,
            "Unix domain sockets are not supported on this platform",
        )
        .into())
    }
}

View on GitHub (pinned to 03af8bcc57)

Solutions

1. Use TCP (host/port) connection options instead of a Unix socket path on non-unix platforms
2. Make the socket-based config conditional on target OS (cfg or env-based config)
3. Compile for a unix target if UDS is a hard requirement

Example fix

// before (fails on Windows)
let opts = PgConnectOptions::new().socket("/var/run/postgresql");
// after
#[cfg(unix)]
let opts = PgConnectOptions::new().socket("/var/run/postgresql");
#[cfg(not(unix))]
let opts = PgConnectOptions::new().host("localhost").port(5432);

#[cfg(not(unix))]
let use_uds = false;
#[cfg(unix)]
let use_uds = std::path::Path::new("/var/run/postgresql").exists();

match pool.connect().await {
    Err(e) if e.to_string().contains("Unix domain sockets are not supported") => {
        // fall back to TCP options
    }
    other => other?,
}

When it happens

Trigger: Using a connection string with a Unix socket path (e.g. `postgres:///db?host=/var/run/postgresql` or `mysql://user@/db?socket=/tmp/mysql.sock`) while compiling/running on Windows or other non-unix targets.

Common situations: Config built for Linux deployed to Windows; shared DATABASE_URL across developer machines with mixed OSes; cross-compiling a service for a non-unix target while the config points at a socket file.

Related errors

• unimplemented!()
• expected to read {} bytes, got {} bytes at EOF
• Hostname did not resolve to any addresses
• 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/49ca43dce583178a. Report an issue: GitHub.