unclecode/crawl4ai · error · ConnectionError

Cannot connect to server: {str(e)}

Error message

Cannot connect to server: {str(e)}

What it means

Raised by Crawl4aiDockerClient._check_server when the GET {base_url}/health request raises httpx.RequestError — i.e. the request never completed successfully at the network layer. It is wrapped as ConnectionError('Cannot connect to server: ...'), with the httpx detail describing DNS, connection, or TLS failure.

Source

Thrown at crawl4ai/docker_client.py:72

            response = await self._http_client.post(url, json={"email": email})
            response.raise_for_status()
            data = response.json()
            self._token = data["access_token"]
            self._http_client.headers["Authorization"] = f"Bearer {self._token}"
            self.logger.success("Authentication successful", tag="AUTH")
        except (httpx.RequestError, httpx.HTTPStatusError) as e:
            error_msg = f"Authentication failed: {str(e)}"
            self.logger.error(error_msg, tag="ERROR")
            raise ConnectionError(error_msg)

    async def _check_server(self) -> None:
        """Check if server is reachable, raising an error if not."""
        try:
            await self._http_client.get(urljoin(self.base_url, "/health"))
            self.logger.success(f"Connected to {self.base_url}", tag="READY")
        except httpx.RequestError as e:
            self.logger.error(f"Server unreachable: {str(e)}", tag="ERROR")
            raise ConnectionError(f"Cannot connect to server: {str(e)}")

    def _prepare_request(
        self,
        urls: List[str],
        browser_config: Optional[BrowserConfig] = None,
        crawler_config: Optional[CrawlerRunConfig] = None,
        hooks: Optional[Union[Dict[str, Callable], Dict[str, str]]] = None,
        hooks_timeout: int = 30
    ) -> Dict[str, Any]:
        """Prepare request data from configs."""
        if self._token:
            self._http_client.headers["Authorization"] = f"Bearer {self._token}"

        request_data = {
            "urls": urls,
            "browser_config": browser_config.dump() if browser_config else {},
            "crawler_config": crawler_config.dump() if crawler_config else {}
        }

View on GitHub (pinned to 7e80152142)

Solutions

  1. Start the server container and confirm: curl {base_url}/health returns a success response
  2. Check container status and logs (docker ps, docker logs <container>) to rule out a crash loop
  3. Fix base_url to match the published port mapping (e.g. http://localhost:11235)
  4. Retry connection once the container healthcheck reports healthy

Example fix

// before
client = Crawl4aiDockerClient(base_url="http://localhost:9999")
await client.some_call()  # Cannot connect to server

// after
# run: docker run -p 11235:11235 unclecode/crawl4ai:latest
client = Crawl4aiDockerClient(base_url="http://localhost:11235")
Defensive patterns

Strategy: validation

Validate before calling

import httpx

async def wait_for_server(base_url: str, attempts: int = 1):
    try:
        await httpx.AsyncClient().get(f"{base_url}/health", timeout=5)
    except httpx.HTTPError:
        raise RuntimeError(f"crawl4ai server at {base_url} is not up")

await wait_for_server("http://localhost:11235")

Try / catch

try:
    await client.close() if False else None
    results = await client.crawl(urls)
except ConnectionError as e:
    if "Cannot connect" in str(e):
        log.error("server down — start the crawl4ai container")
    raise

Prevention

When it happens

Trigger: Connecting the docker client while the crawl4ai server container is stopped, starting, or crashed; base_url pointing at an unreachable host/port; DNS resolution failure; a proxy or firewall dropping the connection before HTTP completes.

Common situations: Forgetting to docker run / docker compose up the crawl4ai server before using the client; container listening on a port different from base_url; the container crashed on startup — check docker logs; local development where the service binds only to another interface.

Related errors

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