{"record":{"id":"e06ef213c863b5d0","repo":"microsoft/autogen","slug":"container-failed-to-start","errorCode":null,"errorMessage":"Container failed to start","messagePattern":"Container failed to start","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py","lineNumber":62,"sourceCode":"    import asyncio_atexit\n    import docker\n    from docker.errors import DockerException, ImageNotFound, NotFound\n    from docker.models.containers import Container\nexcept ImportError as e:\n    raise RuntimeError(\n        \"Missing dependecies for DockerCommandLineCodeExecutor. Please ensure the autogen-ext package was installed with the 'docker' extra.\"\n    ) from e\n\n\nasync def _wait_for_ready(container: Any, timeout: int = 60, stop_time: float = 0.1) -> None:\n    elapsed_time = 0.0\n    while container.status != \"running\" and elapsed_time < timeout:\n        await asyncio.sleep(stop_time)\n        elapsed_time += stop_time\n        await asyncio.to_thread(container.reload)\n        continue\n    if container.status != \"running\":\n        raise ValueError(\"Container failed to start\")\n\n\nA = ParamSpec(\"A\")\n\n\nclass DockerCommandLineCodeExecutorConfig(BaseModel):\n    \"\"\"Configuration for DockerCommandLineCodeExecutor\"\"\"\n\n    image: str = \"python:3-slim\"\n    container_name: Optional[str] = None\n    timeout: int = 60\n    work_dir: Optional[str] = None\n    bind_dir: Optional[str] = None\n    auto_remove: bool = True\n    stop_container: bool = True\n    functions_module: str = \"functions\"\n    extra_volumes: Dict[str, Dict[str, str]] = {}\n    extra_hosts: Dict[str, str] = {}","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py#L44-L80","documentation":"Raised by the Docker executor's _wait_for_ready helper when a freshly created container has not reached status 'running' within the timeout (default 60s, polling every 0.1s with container.reload). It means the container was created but crashed, exited immediately, or the Docker daemon could not transition it to running.","triggerScenarios":"Starting DockerCommandLineCodeExecutor with an image whose entrypoint exits immediately, a nonexistent/corrupt local image, a container name collision with an existing stopped container, or a Docker daemon under heavy load so 60s elapse before the container is running.","commonSituations":"Using a custom image built with a non-detached entrypoint; leftover containers with the same container_name from a previous crashed run; Docker Desktop just started and still initializing; resource exhaustion (out of memory) causing the container to die on start.","solutions":["Run `docker ps -a` and inspect the container: `docker logs <name>` shows why it exited; remove leftover containers with the same name","Test the image manually: docker run --rm <image> echo ok — if it exits, fix the image's entrypoint","Use the default python:3-slim image first to isolate image-specific issues","If the daemon is slow, retry after `docker system prune` or restarting Docker"],"exampleFix":"# before\nexecutor = DockerCommandLineCodeExecutor(image=\"my-custom:latest\")\n\n# after: verify image runs interactively first\n# docker run --rm -it my-custom:latest /bin/sh\nexecutor = DockerCommandLineCodeExecutor(image=\"python:3-slim\")  # known-good baseline","handlingStrategy":"validation","validationCode":"import docker\n\ndef image_runnable(image: str) -> bool:\n    client = docker.from_env()\n    try:\n        return client.containers.run(image, \"echo ok\", remove=True) is not None\n    except docker.errors.ImageNotFound:\n        return False","typeGuard":"null","tryCatchPattern":"try:\n    async with DockerCommandLineCodeExecutor(image=img) as executor:\n        ...\nexcept ValueError as e:\n    if \"failed to start\" in str(e).lower():\n        subprocess.run([\"docker\", \"logs\", container_name])  # inspect why it exited\n        raise","preventionTips":["Validate custom images with `docker run --rm <image> echo ok` before wiring them into the executor","Clean up leftover containers sharing your container_name before runs","Warm up Docker Desktop before test suites that create containers"],"tags":["docker","container","startup","timeout"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}