{"record":{"id":"4cde8710a0e1561d","repo":"microsoft/autogen","slug":"unexpected-error-while-connecting-to-docker-str","errorCode":null,"errorMessage":"Unexpected error while connecting to Docker: {str(e)}","messagePattern":"Unexpected error while connecting to Docker: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py","lineNumber":515,"sourceCode":"\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\n        try:\n            existing_container = await asyncio.to_thread(client.containers.get, self.container_name)\n            await asyncio.to_thread(existing_container.remove, force=True)","sourceCodeStart":497,"sourceCodeEnd":533,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py#L497-L533","documentation":"Generic wrapper raised when docker.from_env() throws something other than the known DockerException/FileNotFoundError case while DockerCommandLineCodeExecutor.start() tries to build a Docker client. The original exception is chained via 'from e', so the message embeds the underlying error text (permissions, TLS config, socket errors, etc.).","triggerScenarios":"Calling await executor.start() when from_env() raises an unexpected exception, e.g. PermissionError on /var/run/docker.sock (not always wrapped as DockerException with FileNotFoundError), malformed DOCKER_HOST/TLS settings in ~/.docker/config.json, or docker-py version incompatibilities.","commonSituations":"Unix permission denied on the Docker socket, DOCKER_HOST=tcp://... pointing at a dead endpoint, corrupt TLS certificates in docker config, corporate proxies intercepting the socket, mismatched docker-py versions after upgrading packages.","solutions":["Read the embedded {str(e)} text to identify the root cause, then fix that (permissions, DOCKER_HOST, TLS config).","If the message mentions permissions on a Unix socket: sudo usermod -aG docker $USER, log out/in, verify with docker ps.","Unset or correct DOCKER_HOST / DOCKER_TLS_VERIFY / DOCKER_CERT_PATH environment variables and test with docker version.","Upgrade/reinstall the docker Python package so it matches your daemon version (pip install -U docker)."],"exampleFix":"# before\nawait executor.start()\n# RuntimeError: Unexpected error while connecting to Docker: PermissionError(.../docker.sock)\n\n# after\n# on the shell, before running the app:\n#   sudo usermod -aG docker $USER && newgrp docker\n#   docker ps   # verify access\nawait executor.start()","handlingStrategy":"try-catch","validationCode":"import subprocess\n\ndef docker_daemon_reachable() -> bool:\n    return subprocess.run([\"docker\", \"info\"], capture_output=True).returncode == 0","typeGuard":null,"tryCatchPattern":"try:\n    await executor.start()\nexcept RuntimeError as e:\n    print(f\"Docker client failed: {e} | root cause: {e.__cause__!r}\")\n    raise","preventionTips":["Keep DOCKER_HOST/DOCKER_CERT_PATH/TLS config consistent across environments.","Verify group membership (id -nG | grep docker) after adding the user to the docker group.","Pin a docker-py version matching your daemon; re-test after upgrades."],"tags":["docker","environment","permissions","executor"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}