What causes "Cannot connect to unix socket {path} ssl:{ssl} [{strerror}]" in aio-libs/aiohttp?

Verify the path: `ls -l /var/run/foo.sock` and `test -S /var/run/foo.sock`.

aio-libs/aiohttp · error · UnixClientConnectorError

Cannot connect to unix socket {path} ssl:{ssl} [{strerror}]

Error message

Cannot connect to unix socket {path} ssl:{ssl} [{strerror}]

What it means

Raised by UnixConnector._create_connection() when loop.create_unix_connection() raises an OSError that is not an asyncio.TimeoutError. aiohttp wraps it as UnixClientConnectorError(path, connection_key, exc) so the caller knows both the socket path and the target request that failed. Typical causes: the socket path does not exist, permissions are wrong, or the socket is not listening.

Source

Thrown at aiohttp/connector.py:1716

    @property
    def path(self) -> str:
        """Path to unix socket."""
        return self._path

    async def _create_connection(
        self, req: ClientRequest, traces: list["Trace"], timeout: "ClientTimeout"
    ) -> ResponseHandler:
        try:
            async with ceil_timeout(
                timeout.sock_connect, ceil_threshold=timeout.ceil_threshold
            ):
                _, proto = await self._loop.create_unix_connection(
                    self._factory, self._path
                )
        except OSError as exc:
            if exc.errno is None and isinstance(exc, asyncio.TimeoutError):
                raise
            raise UnixClientConnectorError(self.path, req.connection_key, exc) from exc

        return proto


class NamedPipeConnector(BaseConnector):
    """Named pipe connector.

    Only supported by the proactor event loop.
    See also: https://docs.python.org/3/library/asyncio-eventloop.html

    path - Windows named pipe path.
    keepalive_timeout - (optional) Keep-alive timeout.
    force_close - Set to True to force close and do reconnect
        after each request (and between redirects).
    limit - The total number of simultaneous connections.
    limit_per_host - Number of simultaneous connections to one host.
    loop - Optional event loop.
    """

View on GitHub (pinned to c0ef574e29)

Solutions

Verify the path: `ls -l /var/run/foo.sock` and `test -S /var/run/foo.sock`.
Ensure the process uid has read/write on the socket.
Confirm the daemon is running and listening on that socket.
Remove stale socket files and restart the server if the path exists but is dead.

Example fix

# before
connector = aiohttp.UnixConnector('/var/run/missing.sock')
# after
connector = aiohttp.UnixConnector('/var/run/real.sock')
# verify: ls -l /var/run/real.sock

Defensive patterns

Strategy: validation

Validate before calling

import os, stat

def unix_socket_ok(path: str) -> bool:
    try:
        st = os.stat(path)
    except OSError:
        return False
    return stat.S_ISSOCK(st.st_mode) and os.access(path, os.R_OK | os.W_OK)

Try / catch

from aiohttp import UnixClientConnectorError
try:
    await session.get(url)
except UnixClientConnectorError as e:
    # e.path is the socket path; e.os_error has errno
    raise

Prevention

Health-check the socket path (existence + permissions) before issuing requests.
Run the client process as a user permitted to access the socket.
Clean up stale socket files in your service lifecycle.

When it happens

Trigger: Requesting a URL whose connector is a UnixConnector pointed at a path that does not exist, is not a socket, has no read/write permission, or whose server has stopped listening.

Common situations: Talking to a docker/mysqld/postgres control socket that isn't running. Wrong path in config. Permission denied because the process runs as the wrong user. Container restart left the socket file behind/stale.

Related errors

AI-assisted analysis of aio-libs/aiohttp@c0ef574e29 (2026-08-04). Data as JSON: /data/errors/d60b8fd9b206e468.json. Report an issue: GitHub.