agentscope-ai/agentscope · error · RuntimeError

Failed to start container

Error message

Failed to start container {self._container_name!r}: {stderr.decode(errors='replace')}

What it means

Raised when `container start` (Apple Containers CLI) returns a non-zero exit code while _start_container_if_stopped attempts to restart a stopped container. The message embeds the container name and the decoded stderr from the CLI subprocess. It indicates the container exists but the runtime refused to start it.

Solutions

Inspect the embedded stderr — it is the direct output of `container start <name>`
Verify the container exists and inspect its state: `container list --all` and `container inspect <name>`
Try starting it manually to reproduce: `container start <name>`
Delete and reprovision the broken container if state is unrecoverable (remove the stale container and re-initialize the workspace)
Ensure the Apple Containers runtime/daemon and macOS version are supported

Example fix

# before: stale/broken container blocks provisioning
# container inspect my-sand shows status=stopped, start fails
class MyWS(AppleContainerWorkspace):
    async def _start_container_if_stopped(self):
        try:
            await super()._start_container_if_stopped()
        except RuntimeError as e:
            # fall back to recreating the container from scratch
            await self._delete_container()
            await self._create_and_start_container()

Defensive patterns

Strategy: fallback

Validate before calling

# before provisioning, check container state via the CLI
import asyncio
async def container_exists(name: str) -> bool:
    p = await asyncio.create_subprocess_exec(
        'container', 'inspect', name,
        stdout=asyncio.subprocess.DEVNULL, stderr=asyncio.subprocess.DEVNULL)
    return await p.wait() == 0

Try / catch

try:
    await ws.initialize()  # or async with ws
except RuntimeError as e:
    if 'Failed to start container' in str(e):
        # recreate container or surface actionable error
        ...
    raise

Prevention

Keep the Apple Containers runtime/daemon running before initializing workspaces
Add health checks that recreate unrecoverable containers
Clean up containers on shutdown to avoid stale states

When it happens

Trigger: Calling workspace APIs that trigger _provision_backend (initialization/reattach) when the named AppleContainer is in a stopped state and the `container start` subprocess fails (e.g. container runtime not running, invalid image state, port conflicts, corrupted container).

Common situations: Apple Container framework daemon not running on macOS, container left in a broken state after a host reboot or OOM kill, name collision with a half-created container, macOS/version mismatch of the container CLI.

Related errors

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/fcd49f2803f1f194. Report an issue: GitHub.

Appendix: source

Thrown at src/agentscope/workspace/_applecontainer/_applecontainer_workspace.py:437

                    self._container_name,
                )
                return

        # Start the container.
        logger.info(
            "AppleContainerWorkspace: starting container %r ...",
            self._container_name,
        )
        process = await asyncio.create_subprocess_exec(
            "container",
            "start",
            self._container_name,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        _, stderr = await process.communicate()
        if process.returncode != 0:
            raise RuntimeError(
                f"Failed to start container {self._container_name!r}: "
                f"{stderr.decode(errors='replace')}",
            )

    async def _create_and_start_container(self) -> None:
        """Create and start the container via ``container run -d``.

        The container runs ``sleep infinity`` to stay alive while the
        gateway is managed independently.
        """
        run_cmd: list[str] = [
            "container",
            "run",
            "-d",
            "--name",
            self._container_name,
            "--cpus",
            str(self.cpus),

View on GitHub (pinned to e90f1c7592)