microsoft/autogen · error · ValueError

Container is not running. Must first be started with either

Error message

Container is not running. Must first be started with either start or a context manager.

What it means

Raised by DockerCommandLineCodeExecutor._execute_command when an exec is attempted while the executor's container is None or the _running flag is False. In practice it means execute_code_blocks was called before start()/entering the context manager, or after stop() — but the usual public entry point execute_code_blocks auto-starts, so hitting this from user code indicates a stopped/failed executor or direct use of internals.

Source

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

        # Attempt to load the function file to check for syntax errors, imports etc.
        exec_result = await self._execute_code_dont_check_setup(
            [CodeBlock(code=func_file_content, language="python")], cancellation_token
        )

        if exec_result.exit_code != 0:
            raise ValueError(f"Functions failed to load: {exec_result.output}")

        self._setup_functions_complete = True

    async def _kill_running_command(self, command: List[str]) -> None:
        if self._container is None or not self._running:
            return
        await asyncio.to_thread(self._container.exec_run, ["pkill", "-f", " ".join(command)])

    async def _execute_command(self, command: List[str], cancellation_token: CancellationToken) -> Tuple[str, int]:
        if self._container is None or not self._running:
            raise ValueError("Container is not running. Must first be started with either start or a context manager.")

        exec_task = asyncio.create_task(asyncio.to_thread(self._container.exec_run, command))
        cancellation_token.link_future(exec_task)

        # Wait for the exec task to finish.
        try:
            result = await exec_task
            exit_code = result.exit_code
            output = result.output.decode("utf-8")
            if exit_code == 124:
                output += "\n Timeout"
            return output, exit_code
        except asyncio.CancelledError:
            # Schedule a task to kill the running command in the background.
            if self._loop and not self._loop.is_closed():
                try:
                    logging.debug(f"Scheduling kill command via run_coroutine_threadsafe on loop {self._loop!r}")
                    future: ConcurrentFuture[None] = asyncio.run_coroutine_threadsafe(

View on GitHub (pinned to 027ecf0a37)

Solutions

Use the executor as an async context manager so lifecycle is handled: `async with DockerCommandLineCodeExecutor() as e: await e.execute_code_blocks(...)`
If managing manually, call `await executor.start()` after construction and again after stop() before executing code
After Docker daemon outages, recreate the executor rather than reusing a stopped instance
Avoid calling private _execute_* methods directly; go through execute_code_blocks

Example fix

# before
executor = DockerCommandLineCodeExecutor()
result = await executor.execute_code_blocks(blocks, ct)  # not started

# after
async with DockerCommandLineCodeExecutor() as executor:
    result = await executor.execute_code_blocks(blocks, ct)

Defensive patterns

Strategy: validation

Validate before calling

null

Type guard

def executor_ready(executor) -> bool:
    return executor._container is not None and executor._running

Try / catch

try:
    result = await executor.execute_code_blocks(blocks, ct)
except ValueError as e:
    if "not running" in str(e):
        await executor.start()
        result = await executor.execute_code_blocks(blocks, ct)

Prevention

Always use `async with DockerCommandLineCodeExecutor() as executor:` so the container lifecycle is correct by construction
Never reuse an executor after stop(); create a fresh instance
Do not call private _execute_* methods from user code

When it happens

Trigger: Calling internal methods (_execute_command, _execute_code_dont_check_setup) without a running container; calling execute_code_blocks after stop() completed (executor not restarted); a container that died between start and execution leaving _running stale. Note the executor used as a context manager (`async with ... as executor`) starts automatically.

Common situations: Keeping a module-level executor and reusing it across requests after a shutdown hook stopped it; a previous container crash combined with the flag not being reset; calling restart() before ever starting, which hits the same guard.

Related errors

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