agentscope-ai/agentscope · critical · RuntimeError

Apple Container CLI is not installed. Install it first…

Error message

Apple Container CLI is not installed. Install it first: https://github.com/apple/container

What it means

AppleContainerWorkspace._check_cli runs the `container` binary to verify the Apple Container CLI; FileNotFoundError from subprocess means the binary is not on PATH, so the workspace raises RuntimeError with the install URL. Provisioning aborts before any container is created.

Solutions

Install Apple Container CLI: brew install container (or see https://github.com/apple/container).
Ensure `container` resolves: which container; add its install dir to PATH.
Verify it runs: container system start.
If on non-macOS, use a different workspace backend (e.g. local or docker-based).

Example fix

# before (fails on Linux/CI)
ws = AppleContainerWorkspace(base_image="ubuntu:24.04")

# after
import sys
if sys.platform == "darwin":
    ws = AppleContainerWorkspace(base_image="ubuntu:24.04")
else:
    ws = LocalWorkspace()  # or another backend

Defensive patterns

Strategy: validation

Validate before calling

import shutil, sys
assert sys.platform == "darwin" and shutil.which("container"), "Apple Container CLI required"

Try / catch

try:
    ws = await AppleContainerWorkspace.create(base_image="ubuntu:24.04")
except RuntimeError as e:
    if "not installed" in str(e):
        ws = LocalWorkspace()  # fallback backend
    else:
        raise

Prevention

Gate AppleContainerWorkspace usage behind sys.platform == 'darwin'.
Install the CLI via brew and verify with `which container` in CI setup scripts.

When it happens

Trigger: Creating an AppleContainerWorkspace on a machine without the apple/container CLI installed (or not on PATH). _check_cli is the first step of _provision_backend, so any constructor/factory call triggers it.

Common situations: Running on Linux/CI (the CLI is macOS-only), fresh macOS without the CLI installed, CLI installed via custom location not on PATH, or running from an environment (venv/launchd) with a stripped PATH.

Related errors

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

Appendix: source

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

        Raises:
            RuntimeError: If the CLI is not installed or the system
                service is not running.
        """
        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

View on GitHub (pinned to e90f1c7592)