microsoft/autogen · error · ValueError

Container failed to start

Error message

Container failed to start

What it means

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.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py:62

    import asyncio_atexit
    import docker
    from docker.errors import DockerException, ImageNotFound, NotFound
    from docker.models.containers import Container
except ImportError as e:
    raise RuntimeError(
        "Missing dependecies for DockerCommandLineCodeExecutor. Please ensure the autogen-ext package was installed with the 'docker' extra."
    ) from e


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


A = ParamSpec("A")


class DockerCommandLineCodeExecutorConfig(BaseModel):
    """Configuration for DockerCommandLineCodeExecutor"""

    image: str = "python:3-slim"
    container_name: Optional[str] = None
    timeout: int = 60
    work_dir: Optional[str] = None
    bind_dir: Optional[str] = None
    auto_remove: bool = True
    stop_container: bool = True
    functions_module: str = "functions"
    extra_volumes: Dict[str, Dict[str, str]] = {}
    extra_hosts: Dict[str, str] = {}

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Run `docker ps -a` and inspect the container: `docker logs <name>` shows why it exited; remove leftover containers with the same name
2. Test the image manually: docker run --rm <image> echo ok — if it exits, fix the image's entrypoint
3. Use the default python:3-slim image first to isolate image-specific issues
4. If the daemon is slow, retry after `docker system prune` or restarting Docker

Example fix

# before
executor = DockerCommandLineCodeExecutor(image="my-custom:latest")

# after: verify image runs interactively first
# docker run --rm -it my-custom:latest /bin/sh
executor = DockerCommandLineCodeExecutor(image="python:3-slim")  # known-good baseline

import docker

def image_runnable(image: str) -> bool:
    client = docker.from_env()
    try:
        return client.containers.run(image, "echo ok", remove=True) is not None
    except docker.errors.ImageNotFound:
        return False

null

try:
    async with DockerCommandLineCodeExecutor(image=img) as executor:
        ...
except ValueError as e:
    if "failed to start" in str(e).lower():
        subprocess.run(["docker", "logs", container_name])  # inspect why it exited
        raise

When it happens

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

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

Related errors

• Failed to start container from image {self._image}. Logs: {l
• Container failed to start
• Container is not running. Must first be started with either
• Failed to restart container. Logs: {logs_str}
• Agent factory with type {type} already exists.

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