agentscope-ai/agentscope · error · RuntimeError

Failed to create container {self._container_name!r}: stderr:

Error message

Failed to create container {self._container_name!r}: stderr: {stderr.decode(errors='replace')}\nstdout: {stdout.decode(errors='replace')}

What it means

Raised when `container run -d` fails during _create_and_start_container, i.e. the Apple Containers CLI could not create the sandbox container. Includes both stderr and stdout of the failed command for diagnosis.

Source

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

            [
                self.base_image,
                "sleep",
                "infinity",
            ],
        )

        logger.info(
            "AppleContainerWorkspace: creating container %r ...",
            self._container_name,
        )
        process = await asyncio.create_subprocess_exec(
            *run_cmd,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await process.communicate()
        if process.returncode != 0:
            raise RuntimeError(
                f"Failed to create container {self._container_name!r}: "
                f"stderr: {stderr.decode(errors='replace')}\n"
                f"stdout: {stdout.decode(errors='replace')}",
            )
        logger.info(
            "AppleContainerWorkspace: container %r created (id=%s)",
            self._container_name,
            stdout.decode(errors="replace").strip(),
        )

    # ── internals: bootstrap ────────────────────────────────────

    def _bootstrap_commands(self) -> list[str]:
        """Shell commands that provision this container once.

        Only runs when the gateway script is missing (fresh container
        or prior interrupted bootstrap). Every step is idempotent.

View on GitHub (pinned to e90f1c7592)

Solutions

Check stderr/stdout in the message for the exact CLI error
Verify the image exists locally: `container images` (pull it if missing)
Ensure the container name is not already in use: `container list`
Confirm the Apple Containers runtime is available and the macOS version is supported
Retry initialization after fixing the underlying CLI issue

Example fix

# before
ws = AppleContainerWorkspace(container_name="sand", image="missing-img:latest")
await ws.__aenter__()  # raises RuntimeError

# after
# verify/pull image first
# container images  ->  container pull <image>
ws = AppleContainerWorkspace(container_name="sand", image="example.com/img:tag")
await ws.__aenter__()

Defensive patterns

Strategy: try-catch

Validate before calling

import asyncio, shutil
async def image_available(image: str) -> bool:
    if not shutil.which('container'):
        return False
    p = await asyncio.create_subprocess_exec('container', 'images')
    out, _ = await p.communicate()
    return image in out.decode()

Try / catch

try:
    async with AppleContainerWorkspace(...) as ws:
        ...
except RuntimeError as e:
    # message contains the raw `container run` stderr/stdout
    log.error('container create failed: %s', e)
    raise

Prevention

Pre-pull the container image before first run
Use unique container names per session/workspace
Pin image tags that are known to work with your macOS version

When it happens

Trigger: Workspace initialization on a fresh environment where the container image is missing/not pulled, the container name is already taken, the runtime is unavailable, or `container run` rejects flags (image reference typo, unsupported macOS).

Common situations: First-run on a machine without the required container image, image registry unreachable, name collision with an existing container, Apple Container runtime not installed/enabled on the macOS version.

Related errors

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