cloudflare/pingora · error

non-pathname unix sockets not supported as peer

Error message

non-pathname unix sockets not supported as peer

What it means

When the generic L4 connector dials a SocketAddr::Unix peer it must pass a filesystem path to connect_uds(); tokio's as_pathname() returns None for abstract or unnamed Linux sockets, and pingora .expect()s Some(path), panicking with 'non-pathname unix sockets not supported as peer'. pingora's own constructors (HttpPeer::new_uds, BasicPeer::new_uds) build addresses via UnixSocketAddr::from_pathname, so this only fires when a Peer or SocketAddr::Unix was assembled by other means with an abstract/unnamed address.

Source

Thrown at pingora-core/src/connectors/l4.rs:194

                        Ok(socket) => {
                            local_addr = connect_attempt.local_addr();
                            debug!("connected to new server: {}", peer.address());
                            Ok(socket.into())
                        }
                        Err(e) => {
                            let c = format!("Fail to connect to {peer}");
                            match e.etype() {
                                SocketError | BindError => Error::e_because(InternalError, c, e),
                                _ => Err(e.more_context(c)),
                            }
                        }
                    }
                }
                #[cfg(unix)]
                SocketAddr::Unix(addr) => {
                    let connect_future = connect_uds(
                        addr.as_pathname()
                            .expect("non-pathname unix sockets not supported as peer"),
                    );
                    let conn_res = match peer.connection_timeout() {
                        Some(t) => pingora_timeout::timeout(t, connect_future)
                            .await
                            .explain_err(ConnectTimedout, |_| {
                                format!("timeout {t:?} connecting to server {peer}")
                            })?,
                        None => connect_future.await,
                    };
                    match conn_res {
                        Ok(socket) => {
                            debug!("connected to new server: {}", peer.address());
                            Ok(socket.into())
                        }
                        Err(e) => {
                            let c = format!("Fail to connect to {peer}");
                            match e.etype() {
                                SocketError | BindError => Error::e_because(InternalError, c, e),

View on GitHub (pinned to 0046038bd4)

Solutions

1. Use a real filesystem path: HttpPeer::new_uds("/run/svc.sock", tls, sni) — from_pathname() itself rejects interior NUL bytes for you
2. In custom Peer impls, only ever return pathname-based Unix addresses from address()
3. If the target truly is an abstract socket, connect to it outside pingora's L4 connector and bridge over TCP/localhost

Example fix

// before: custom peer built from an abstract address (as_pathname() -> None)
let peer = HttpPeer::new_from_sockaddr(abstract_unix_peer_addr(), false, "svc".into());

// after: a real pathname UDS peer
let peer = HttpPeer::new_uds("/run/svc.sock", false, "svc".into())?;

// Reject abstract/unnamed UDS peers before handing them to the connector
use pingora_core::protocols::l4::socket::SocketAddr;
fn ensure_pathname_peer<P: pingora_core::upstreams::peer::Peer>(peer: &P) -> Result<()> {
    if let SocketAddr::Unix(addr) = peer.address() {
        if addr.as_pathname().is_none() {
            return Err(pingora_error::Error::explain(
                pingora_error::ErrorType::InternalError,
                "abstract unix sockets are not supported as peers",
            ));
        }
    }
    Ok(())
}

When it happens

Trigger: A custom Peer implementation, or code calling HttpPeer::new_from_sockaddr/BasicPeer::new_from_sockaddr directly, supplies SocketAddr::Unix holding an abstract address (path beginning with a NUL byte, '@name' style); the first connection attempt panics inside connectors/l4.rs:194.

Common situations: Targeting services listening on the Linux abstract namespace (systemd-adjacent/Android-style daemons); building peers from the address of an accepted socket; custom address parsers accepting 'unix:@foo' strings.

Related errors

• non-pathname unix sockets not supported as peer
• Tried to listen with no addr specified
• must have read body buf
• body buf exists once a partial chunk head was buffered
• body buf exists once a chunk was parsed out of it

AI-assisted analysis of cloudflare/pingora@0046038bd4 (2026-08-16). Data as JSON: /api/errors/2d447ea712f9a374. Report an issue: GitHub.