{"record":{"id":"0ee72f67f2873e58","repo":"microsoft/autogen","slug":"failed-to-connect-to-docker-please-ensure-docker","errorCode":null,"errorMessage":"Failed to connect to Docker. Please ensure Docker is installed and running.","messagePattern":"Failed to connect to Docker\\. Please ensure Docker is installed and running\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py","lineNumber":512,"sourceCode":"\n    async def start(self) -> None:\n        \"\"\"(Experimental) Start the code executor.\n\n        This method sets the working environment variables, connects to Docker and starts the code executor.\n        If no working directory was provided to the code executor, it creates a temporary directory and sets it as the code executor working directory.\n        \"\"\"\n\n        if self._work_dir is None and self._temp_dir is None:\n            self._temp_dir = tempfile.TemporaryDirectory()\n            self._temp_dir_path = Path(self._temp_dir.name)\n            self._temp_dir_path.mkdir(exist_ok=True)\n\n        # Start a container from the image, read to exec commands later\n        try:\n            client = docker.from_env()\n        except DockerException as e:\n            if \"FileNotFoundError\" in str(e):\n                raise RuntimeError(\"Failed to connect to Docker. Please ensure Docker is installed and running.\") from e\n            raise\n        except Exception as e:\n            raise RuntimeError(f\"Unexpected error while connecting to Docker: {str(e)}\") from e\n\n        # Check if the image exists\n        try:\n            await asyncio.to_thread(client.images.get, self._image)\n        except ImageNotFound:\n            # TODO logger\n            logging.info(f\"Pulling image {self._image}...\")\n            # Let the docker exception escape if this fails.\n            await asyncio.to_thread(client.images.pull, self._image)\n\n        # Prepare the command (if needed)\n        shell_command = \"/bin/sh\"\n        command = [\"-c\", f\"{(self._init_command)};exec {shell_command}\"] if self._init_command else None\n\n        # Check if a container with the same name already exists and remove it","sourceCodeStart":494,"sourceCodeEnd":530,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py#L494-L530","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"# before\nexecutor = DockerCommandLineCodeExecutor()\nawait executor.start()  # RuntimeError: Failed to connect to Docker...\n\n# after\nimport subprocess, sys\nif subprocess.run([\"docker\", \"info\"], capture_output=True).returncode != 0:\n    sys.exit(\"Docker daemon is not reachable - start Docker first.\")\nexecutor = DockerCommandLineCodeExecutor()\nawait executor.start()","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\n\ndef docker_available() -> bool:\n    host = os.environ.get(\"DOCKER_HOST\", \"\")\n    if host.startswith(\"unix://\"):\n        return Path(host.removeprefix(\"unix://\")).exists()\n    if host:\n        return True  # tcp host; full check needs a ping\n    return Path(\"/var/run/docker.sock\").exists()","typeGuard":null,"tryCatchPattern":"try:\n    await executor.start()\nexcept RuntimeError as e:\n    if \"Failed to connect to Docker\" in str(e):\n        raise SystemExit(f\"Docker unavailable: {e}\")  # environment problem, not a code bug\n    raise","preventionTips":["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."],"tags":["docker","environment","executor","runtime"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}