microsoft/autogen · critical · RuntimeError

Failed to connect to Docker. Please ensure Docker is install

Error message

Failed to connect to Docker. Please ensure Docker is installed and running.

What it means

Raised by DockerCommandLineCodeExecutor.start() when docker.from_env() fails with a DockerException whose string contains 'FileNotFoundError'. This means the Docker SDK could not find the Docker socket/CLI (typically /var/run/docker.sock missing or DOCKER_HOST pointing nowhere), so the executor cannot launch its sandbox container.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py:512

    async def start(self) -> None:
        """(Experimental) Start the code executor.

        This method sets the working environment variables, connects to Docker and starts the code executor.
        If no working directory was provided to the code executor, it creates a temporary directory and sets it as the code executor working directory.
        """

        if self._work_dir is None and self._temp_dir is None:
            self._temp_dir = tempfile.TemporaryDirectory()
            self._temp_dir_path = Path(self._temp_dir.name)
            self._temp_dir_path.mkdir(exist_ok=True)

        # Start a container from the image, read to exec commands later
        try:
            client = docker.from_env()
        except DockerException as e:
            if "FileNotFoundError" in str(e):
                raise RuntimeError("Failed to connect to Docker. Please ensure Docker is installed and running.") from e
            raise
        except Exception as e:
            raise RuntimeError(f"Unexpected error while connecting to Docker: {str(e)}") from e

        # Check if the image exists
        try:
            await asyncio.to_thread(client.images.get, self._image)
        except ImageNotFound:
            # TODO logger
            logging.info(f"Pulling image {self._image}...")
            # Let the docker exception escape if this fails.
            await asyncio.to_thread(client.images.pull, self._image)

        # Prepare the command (if needed)
        shell_command = "/bin/sh"
        command = ["-c", f"{(self._init_command)};exec {shell_command}"] if self._init_command else None

        # Check if a container with the same name already exists and remove it

View on GitHub (pinned to 027ecf0a37)

Solutions

Start the Docker daemon (open Docker Desktop, or sudo systemctl start docker on Linux) and verify with docker info.
Install Docker if missing, following https://docs.docker.com/get-docker/.
If Docker runs but access is denied, add your user to the docker group (sudo usermod -aG docker $USER) and re-login, or verify DOCKER_HOST/DOCKER_CONTEXT env vars point to a reachable daemon.
If you cannot use Docker, switch to a different code executor (e.g. LocalCommandLineCodeExecutor, accepting the safety warning).

Example fix

# before
executor = DockerCommandLineCodeExecutor()
await executor.start()  # RuntimeError: Failed to connect to Docker...

# after
import subprocess, sys
if subprocess.run(["docker", "info"], capture_output=True).returncode != 0:
    sys.exit("Docker daemon is not reachable - start Docker first.")
executor = DockerCommandLineCodeExecutor()
await executor.start()

Defensive patterns

Strategy: validation

Validate before calling

import os
from pathlib import Path

def docker_available() -> bool:
    host = os.environ.get("DOCKER_HOST", "")
    if host.startswith("unix://"):
        return Path(host.removeprefix("unix://")).exists()
    if host:
        return True  # tcp host; full check needs a ping
    return Path("/var/run/docker.sock").exists()

Try / catch

try:
    await executor.start()
except RuntimeError as e:
    if "Failed to connect to Docker" in str(e):
        raise SystemExit(f"Docker unavailable: {e}")  # environment problem, not a code bug
    raise

Prevention

Run docker info in CI before tests that use DockerCommandLineCodeExecutor.
Add a Docker service/sidecar to CI jobs exercising this executor.
Fail fast at app startup with a socket-existence check instead of deep inside agent runs.

When it happens

Trigger: Calling await DockerCommandLineCodeExecutor(...).start() (directly or via an agent runtime that auto-starts the executor) on a machine where the Docker daemon is not running, Docker is not installed, or the user lacks permission on the Unix socket so from_env() surfaces FileNotFoundError inside DockerException.

Common situations: CI runners without a Docker sidecar, WSL2 where Docker Desktop is not started, macOS/Windows with Docker Desktop quit, containers/pods where the Docker socket is not mounted, remote DOCKER_HOST env var misconfigured.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/0ee72f67f2873e58. Report an issue: GitHub.