agentscope-ai/agentscope · critical · RuntimeError

Apple Container CLI is not available. Ensure it is installed

Error message

Apple Container CLI is not available. Ensure it is installed and running: `container system start`.\nstderr: {stderr.decode(errors='replace')}

What it means

_check_cli found the `container` binary but invoking it returned a non-zero exit code, meaning the CLI is installed but its backing service/daemon isn't running. The error suggests `container system start` and includes stderr.

Source

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

        try:
            process = await asyncio.create_subprocess_exec(
                "container",
                "system",
                "version",
                "--format",
                "json",
                stdout=asyncio.subprocess.PIPE,
                stderr=asyncio.subprocess.PIPE,
            )
            stdout, stderr = await process.communicate()
        except FileNotFoundError as e:
            # The ``container`` binary itself is missing.
            raise RuntimeError(
                "Apple Container CLI is not installed. Install it "
                "first: https://github.com/apple/container",
            ) from e
        if process.returncode != 0:
            raise RuntimeError(
                "Apple Container CLI is not available. "
                "Ensure it is installed and running: "
                "`container system start`.\n"
                f"stderr: {stderr.decode(errors='replace')}",
            )
        logger.info(
            "AppleContainerWorkspace: CLI OK — %s",
            stdout.decode(errors="replace").strip(),
        )

    # ── internals: image management ─────────────────────────────

    @staticmethod
    def _normalize_image_ref(ref: str) -> str:
        """Normalize an OCI image reference for comparison.

        Strips the default registry (``docker.io``) and the default
        namespace (``library``) so that short references like

View on GitHub (pinned to e90f1c7592)

Solutions

1. Run: container system start (may require sudo).
2. Check service status: container system info; read stderr embedded in the error.
3. Update the CLI and macOS to versions that satisfy apple/container requirements.
4. If the service won't start, check Virtualization Framework support and free disk space.

Example fix

# shell
# before: error on workspace creation
container system start
# then retry creating AppleContainerWorkspace

import subprocess
r = subprocess.run(["container", "system", "info"], capture_output=True)
assert r.returncode == 0, "start service: container system start"

try:
    ws = await AppleContainerWorkspace.create(base_image="ubuntu:24.04")
except RuntimeError as e:
    if "not available" in str(e):
        subprocess.run(["container", "system", "start"], check=True)
        ws = await AppleContainerWorkspace.create(base_image="ubuntu:24.04")
    else:
        raise

When it happens

Trigger: Creating an AppleContainerWorkspace when the container service is stopped, needs root/privilege, first-run setup incomplete, or macOS virtualization framework errors. Raised from _check_cli during provisioning.

Common situations: After macOS reboot before starting the service, service crashed, macOS version lacking/incomplete Virtualization framework support, or missing permissions for the daemon.

Related errors

• Apple Container CLI is not installed. Install it first: http
• not found in container: {path}\nstderr: {result.stderr.decod
• container cp failed (exit {process.returncode}): {stderr.dec
• Failed to pull image {self.base_image!r}: {stderr.decode(err
• Failed to start container {self._container_name!r}: {stderr.

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