{"record":{"id":"d60b8fd9b206e468","repo":"aio-libs/aiohttp","slug":"cannot-connect-to-unix-socket-path-ssl-ssl-s","errorCode":null,"errorMessage":"Cannot connect to unix socket {path} ssl:{ssl} [{strerror}]","messagePattern":"Cannot connect to unix socket (.+?) ssl:(.+?) \\[(.+?)\\]","errorType":"exception","errorClass":"UnixClientConnectorError","httpStatus":null,"severity":"error","filePath":"aiohttp/connector.py","lineNumber":1716,"sourceCode":"    @property\n    def path(self) -> str:\n        \"\"\"Path to unix socket.\"\"\"\n        return self._path\n\n    async def _create_connection(\n        self, req: ClientRequest, traces: list[\"Trace\"], timeout: \"ClientTimeout\"\n    ) -> ResponseHandler:\n        try:\n            async with ceil_timeout(\n                timeout.sock_connect, ceil_threshold=timeout.ceil_threshold\n            ):\n                _, proto = await self._loop.create_unix_connection(\n                    self._factory, self._path\n                )\n        except OSError as exc:\n            if exc.errno is None and isinstance(exc, asyncio.TimeoutError):\n                raise\n            raise UnixClientConnectorError(self.path, req.connection_key, exc) from exc\n\n        return proto\n\n\nclass NamedPipeConnector(BaseConnector):\n    \"\"\"Named pipe connector.\n\n    Only supported by the proactor event loop.\n    See also: https://docs.python.org/3/library/asyncio-eventloop.html\n\n    path - Windows named pipe path.\n    keepalive_timeout - (optional) Keep-alive timeout.\n    force_close - Set to True to force close and do reconnect\n        after each request (and between redirects).\n    limit - The total number of simultaneous connections.\n    limit_per_host - Number of simultaneous connections to one host.\n    loop - Optional event loop.\n    \"\"\"","sourceCodeStart":1698,"sourceCodeEnd":1734,"githubUrl":"https://github.com/aio-libs/aiohttp/blob/d041d4d0fd48c3f0832084d33be16cf1c4835f85/aiohttp/connector.py#L1698-L1734","documentation":"Raised as UnixClientConnectorError when UnixConnector._create_connection fails to connect to a Unix domain socket. The original OSError (except asyncio.TimeoutError) is wrapped with the socket path, connection key, and underlying OS error string. This is the Unix-socket analogue of ClientConnectorError.","triggerScenarios":"Using UnixConnector(path=...) or an http+unix:// URL when the socket file does not exist, the server process is not listening, or the process lacks permission to access the socket file. Also raised when the connection is refused.","commonSituations":"Connecting to a Docker daemon socket (/var/run/docker.sock) that is not running; targeting a PostgreSQL or Redis Unix socket with the wrong path; running on a system where the socket lives in a different directory; file permission mismatch between the server process and the aiohttp client process.","solutions":["Verify the socket file exists: ls -la /path/to/socket.sock","Confirm the server process is listening on the socket: ss -lx | grep socket_name","Check file permissions on the socket — the aiohttp process needs read/write access","Catch aiohttp.UnixClientConnectorError (or its parent ClientConnectorError) and retry with backoff for transient failures"],"exampleFix":"# before\nconnector = UnixConnector(path='/tmp/myapp.sock')\nsession = ClientSession(connector=connector)\nawait session.get('http://localhost/info')\n\n# after\nimport os, aiohttp\nif not os.path.exists('/tmp/myapp.sock'):\n    raise FileNotFoundError('Socket not found at /tmp/myapp.sock')\ntry:\n    resp = await session.get('http://localhost/info')\nexcept aiohttp.UnixClientConnectorError as e:\n    log.error('Socket connect failed: %s', e)","handlingStrategy":"try-catch","validationCode":"import os, socket\npath = '/tmp/myapp.sock'\nif not os.path.exists(path):\n    raise FileNotFoundError(f'Socket {path} does not exist')\ntry:\n    s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)\n    s.connect(path)\n    s.close()\nexcept OSError:\n    raise ConnectionError(f'Cannot reach socket {path}')","typeGuard":null,"tryCatchPattern":"try:\n    resp = await session.get(url)\nexcept aiohttp.UnixClientConnectorError as e:\n    log.warning('Unix socket unavailable: %s (errno %s)', e.os_error.strerror, e.os_error.errno)\n    # retry or fall back to TCP","preventionTips":["Check os.path.exists on the socket path before creating the connector","Ensure the server process starts before the client connects","Verify socket file permissions match the client process UID/GID"],"tags":["network","unix-socket","connector","connection-error"],"backgroundTag":null,"analyzedSha":"d041d4d0fd48c3f0832084d33be16cf1c4835f85","analyzedAt":"2026-08-11T20:44:15.550Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}