unclecode/crawl4ai · error · ConnectionTimeoutError

Request timed out: {str(e)}

Error message

Request timed out: {str(e)}

What it means

Raised when aiohttp raises ServerTimeoutError (or asyncio.TimeoutError) during an HTTP-mode crawl. The exception is converted to ConnectionTimeoutError with the original message. This reflects the server accepting the connection but failing to respond in time, or the overall request deadline expiring.

Source

Thrown at crawl4ai/async_crawler_strategy.py:2780

                        if not encoding:
                            detection_result = await asyncio.to_thread(chardet.detect, content.tobytes())
                            encoding = detection_result['encoding'] or 'utf-8'
                        html = content.tobytes().decode(encoding, errors='replace')

                    result = AsyncCrawlResponse(
                        html=html,
                        response_headers=response_headers,
                        status_code=response.status,
                        redirected_url=str(response.url),
                        downloaded_files=downloaded_files,
                    )

                    await self.hooks['after_request'](result)
                    return result

            except aiohttp.ServerTimeoutError as e:
                await self.hooks['on_error'](e)
                raise ConnectionTimeoutError(f"Request timed out: {str(e)}")
                
            except aiohttp.ClientConnectorError as e:
                await self.hooks['on_error'](e)
                raise ConnectionError(f"Connection failed: {str(e)}")
                
            except aiohttp.ClientError as e:
                await self.hooks['on_error'](e)
                raise HTTPCrawlerError(f"HTTP client error: {str(e)}")
            
            except asyncio.exceptions.TimeoutError as e:
                await self.hooks['on_error'](e)
                raise ConnectionTimeoutError(f"Request timed out: {str(e)}")
            
            except Exception as e:
                await self.hooks['on_error'](e)
                raise HTTPCrawlerError(f"HTTP request failed: {str(e)}")

    async def crawl(

View on GitHub (pinned to 7e80152142)

Solutions

1. Increase the request timeout in the HTTP crawler's session config (BrowserConfig timeout options / aiohttp ClientTimeout).
2. Retry with backoff: server timeouts are frequently transient.
3. For large downloads, stream or raise total timeout; for flaky keep-alive, lower keepalive_timeout or use force_close.

Example fix

// before
result = await crawler.arun(url)  # hangs then raises ConnectionTimeoutError

// after
import aiohttp
from crawl4ai.async_crawler_strategy import ConnectionTimeoutError
for attempt in range(3):
    try:
        result = await crawler.arun(url)
        break
    except ConnectionTimeoutError:
        await asyncio.sleep(2 ** attempt)

from crawl4ai.async_crawler_strategy import ConnectionTimeoutError

for attempt in range(3):
    try:
        result = await crawler.arun(url)
        break
    except ConnectionTimeoutError:
        await asyncio.sleep(2 ** attempt)
else:
    raise

When it happens

Trigger: Slow endpoints that exceed aiohttp's timeout; the default ClientTimeout elapsed on large downloads; servers that hang on keep-alive connections; proxies that stall. Distinct from ClientConnectorError (connection never established).

Common situations: Large file/page downloads with default timeouts; overloaded target servers; network paths with high latency; misconfigured proxy timeouts shorter than the target's response time.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Failed on navigating ACS-GOTO: {str(e)}
• Unexpected status code for {url}
• Connection failed: {str(e)}
• HTTP client error: {str(e)}
• HTTP request failed: {str(e)}

AI-assisted analysis of unclecode/crawl4ai@7e80152142 (2026-08-14). Data as JSON: /api/errors/f788bae851abeaad. Report an issue: GitHub.