{"record":{"id":"7ef1209cd0acbab6","repo":"microsoft/autogen","slug":"container-failed-to-start-7ef120","errorCode":null,"errorMessage":"Container failed to start","messagePattern":"Container failed to start","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_jupyter_server.py","lineNumber":415,"sourceCode":"        if stop_container:\n            atexit.register(cleanup)\n\n        self._cleanup_func = cleanup\n        self._stop_container = stop_container\n\n    @property\n    def connection_info(self) -> JupyterConnectionInfo:\n        return JupyterConnectionInfo(host=\"127.0.0.1\", use_https=False, port=self._port, token=self._token)\n\n    def _wait_for_ready(self, 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            sleep(stop_time)\n            elapsed_time += stop_time\n            container.reload()\n            continue\n        if container.status != \"running\":\n            raise ValueError(\"Container failed to start\")\n\n    async def stop(self) -> None:\n        loop = asyncio.get_event_loop()\n        await loop.run_in_executor(None, self._cleanup_func)\n\n    async def get_client(self) -> JupyterClient:\n        return JupyterClient(self.connection_info)\n\n    async def __aenter__(self) -> Self:\n        return self\n\n    async def __aexit__(\n        self, exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]\n    ) -> None:\n        await self.stop()\n","sourceCodeStart":397,"sourceCodeEnd":431,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_jupyter_server.py#L397-L431","documentation":"Raised by DockerJupyterServer._wait_for_ready: it polls container.status every 0.1s for up to 60 seconds; if the Jupyter container never reaches 'running' status within the timeout, it raises ValueError('Container failed to start'). Note it checks container status, not whether Jupyter inside is actually serving.","triggerScenarios":"The Jupyter container crashing on startup (bad TOKEN env, missing python modules in a custom image), the container being OOM-killed or immediately exited so status stays 'exited'/'restarting', or a very slow host where the container is stuck in 'created'.","commonSituations":"Custom Docker images whose entrypoint fails due to missing dependencies, memory-constrained CI runners killing the container, Docker daemon hiccups, images built for the wrong architecture.","solutions":["Inspect the container manually: docker ps -a then docker logs <id> to see why Jupyter exited, and fix the image/entrypoint.","Use the default image (no custom image name), which is known-good.","Free host memory / raise container memory limits if the container is OOM-killed.","Rebuild custom images for the host platform (docker build --platform linux/amd64 ...)."],"exampleFix":"# before\nserver = DockerJupyterServer(custom_image_name=\"my-jupyter\")  # ValueError: Container failed to start\n\n# after\n# diagnose: docker run --rm my-jupyter  -> ModuleNotFoundError: jupyter_server\n# fix Dockerfile to install requirements, then:\nserver = DockerJupyterServer(custom_image_name=\"my-jupyter\")","handlingStrategy":"try-catch","validationCode":"import docker\n\ndef container_can_run(image: str) -> bool:\n    c = docker.from_env()\n    out = c.containers.run(image, command=\"sleep\", detach=True)\n    ok = out.status == \"running\"\n    out.remove(force=True)\n    return ok","typeGuard":null,"tryCatchPattern":"try:\n    server = DockerJupyterServer(custom_image_name=name)\nexcept ValueError as e:\n    if str(e) == \"Container failed to start\":\n        raise RuntimeError(\"Jupyter image broken - run `docker run --rm <image>` to inspect\") from e\n    raise","preventionTips":["Smoke-test custom Jupyter images in CI with a plain docker run.","Keep memory headroom on hosts/CI runners that start Jupyter containers.","Prefer the default image unless customization is required."],"tags":["docker","container","jupyter","timeout"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}