agentscope-ai/agentscope · critical · RuntimeError

Apple Container CLI is not installed. Install it first: http

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.

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)

Solutions

1. Install Apple Container CLI: brew install container (or see https://github.com/apple/container).
2. Ensure `container` resolves: which container; add its install dir to PATH.
3. Verify it runs: container system start.
4. 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

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

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

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

• Apple Container CLI is not available. Ensure it is installed
• 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/a679ea408f80665f. Report an issue: GitHub.