microsoft/autogen · critical · ValueError

Container failed to start

Error message

Container failed to start

What it means

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.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/code_executors/docker_jupyter/_jupyter_server.py:415

        if stop_container:
            atexit.register(cleanup)

        self._cleanup_func = cleanup
        self._stop_container = stop_container

    @property
    def connection_info(self) -> JupyterConnectionInfo:
        return JupyterConnectionInfo(host="127.0.0.1", use_https=False, port=self._port, token=self._token)

    def _wait_for_ready(self, container: Any, timeout: int = 60, stop_time: float = 0.1) -> None:
        elapsed_time = 0.0
        while container.status != "running" and elapsed_time < timeout:
            sleep(stop_time)
            elapsed_time += stop_time
            container.reload()
            continue
        if container.status != "running":
            raise ValueError("Container failed to start")

    async def stop(self) -> None:
        loop = asyncio.get_event_loop()
        await loop.run_in_executor(None, self._cleanup_func)

    async def get_client(self) -> JupyterClient:
        return JupyterClient(self.connection_info)

    async def __aenter__(self) -> Self:
        return self

    async def __aexit__(
        self, exc_type: Optional[Type[BaseException]], exc_val: Optional[BaseException], exc_tb: Optional[TracebackType]
    ) -> None:
        await self.stop()

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Inspect the container manually: docker ps -a then docker logs <id> to see why Jupyter exited, and fix the image/entrypoint.
2. Use the default image (no custom image name), which is known-good.
3. Free host memory / raise container memory limits if the container is OOM-killed.
4. Rebuild custom images for the host platform (docker build --platform linux/amd64 ...).

Example fix

# before
server = DockerJupyterServer(custom_image_name="my-jupyter")  # ValueError: Container failed to start

# after
# diagnose: docker run --rm my-jupyter  -> ModuleNotFoundError: jupyter_server
# fix Dockerfile to install requirements, then:
server = DockerJupyterServer(custom_image_name="my-jupyter")

import docker

def container_can_run(image: str) -> bool:
    c = docker.from_env()
    out = c.containers.run(image, command="sleep", detach=True)
    ok = out.status == "running"
    out.remove(force=True)
    return ok

try:
    server = DockerJupyterServer(custom_image_name=name)
except ValueError as e:
    if str(e) == "Container failed to start":
        raise RuntimeError("Jupyter image broken - run `docker run --rm <image>` to inspect") from e
    raise

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

• Container failed to start
• Container is not running. Must first be started with either
• Failed to restart container. Logs: {logs_str}
• Failed to start container from image {self._image}. Logs: {l
• Kernel {self._kernel_name} is not installed.

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