aio-libs/aiohttp · error · ConnectionTimeoutError

Connection timeout to host {url}

Error message

Connection timeout to host {url}

What it means

Raised in _connect_and_send_request (client.py:240) when TCPConnector.connect() does not complete within the configured sock_connect timeout. The asyncio.TimeoutError is wrapped and re-raised as ConnectionTimeoutError with the target URL. It is a subclass of ServerTimeoutError/ClientError.

Source

Thrown at aiohttp/client.py:240

)

_RetType_co = TypeVar(
    "_RetType_co",
    bound="ClientResponse | ClientWebSocketResponse[bool]",
    covariant=True,
)
_CharsetResolver = Callable[[ClientResponse, bytes], str]


# Module-level (not a closure) so it has a stable identity for the
# ``_cached_build_client_middlewares`` cache key.
async def _connect_and_send_request(req: ClientRequest) -> ClientResponse:
    connector = req._session._connector
    assert connector is not None
    try:
        conn = await connector.connect(req, traces=req._traces, timeout=req._timeout)
    except asyncio.TimeoutError as exc:
        raise ConnectionTimeoutError(f"Connection timeout to host {req.url}") from exc

    assert conn.protocol is not None
    conn.protocol.set_response_params(**req._response_params)
    try:
        resp = await req._send(conn)
        try:
            await resp.start(conn)
        except BaseException:
            resp.close()
            raise
    except BaseException:
        conn.close()
        raise
    return resp


@final
class ClientSession:

View on GitHub (pinned to c0ef574e29)

Solutions

1. Raise sock_connect via ClientTimeout(sock_connect=N) to match real network latency.
2. Verify reachability: ping/telnet/curl to the host and port; check DNS with nslookup.
3. Retry with bounded backoff for transient congestion, and check proxy configuration if applicable.

Example fix

# before
async with aiohttp.ClientSession() as s:
    await s.get('https://slow.example')  # default/short sock_connect

# after
timeout = aiohttp.ClientTimeout(sock_connect=30)
async with aiohttp.ClientSession(timeout=timeout) as s:
    await s.get('https://slow.example')

timeout = aiohttp.ClientTimeout(sock_connect=30)
async with aiohttp.ClientSession(timeout=timeout) as s:
    await s.get(url)

try:
    async with session.get(url) as r:
        ...
except aiohttp.ConnectionTimeoutError as exc:
    # retry with backoff or report unreachable host
    ...

When it happens

Trigger: session.request(...) / session.ws_connect(...) where the TCP (or TLS) handshake to the target host exceeds ClientTimeout.sock_connect (default 5 minutes if unset, but commonly overridden).

Common situations: Unreachable/slow host, firewall dropping SYN packets, DNS resolves to a dead IP, proxy connect delay, overloaded server backlog, or an aggressively small sock_connect value.

Related errors

• timeout parameter cannot be of {type} type, please use 'time
• Connection lost
• base_url must have a trailing '/'
• ssl should be SSLContext, Fingerprint, or bool, got {ssl!r}
• Session and connector have to use same event loop

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