agentscope-ai/agentscope · error · RuntimeError

Failed to pull image {self.base_image!r}: {stderr.decode(err

Error message

Failed to pull image {self.base_image!r}: {stderr.decode(errors='replace')}

What it means

During provisioning, _pull_image_if_needed runs `container image pull <base_image>`; a non-zero exit raises RuntimeError with the pull stderr. The base image could not be fetched into the local image store.

Source

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

                        )
                        return

        # Pull the image.
        logger.info(
            "AppleContainerWorkspace: pulling image %r ...",
            self.base_image,
        )
        process = await asyncio.create_subprocess_exec(
            "container",
            "image",
            "pull",
            self.base_image,
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        _, stderr = await process.communicate()
        if process.returncode != 0:
            raise RuntimeError(
                f"Failed to pull image {self.base_image!r}: "
                f"{stderr.decode(errors='replace')}",
            )
        logger.info(
            "AppleContainerWorkspace: image %r pulled successfully",
            self.base_image,
        )

    # ── internals: container lifecycle ──────────────────────────

    async def _find_existing_container(self) -> str | None:
        """Find a container by name via ``container list --format json``.

        Returns:
            `str | None`:
                The container ID if found, ``None`` otherwise.
        """
        process = await asyncio.create_subprocess_exec(

View on GitHub (pinned to e90f1c7592)

Solutions

1. Verify the image name/tag exists: docker manifest inspect <image> or check the registry page.
2. Use a known-good tag, e.g. 'ubuntu:24.04' or 'python:3.12-slim'.
3. For private registries, authenticate first (container login / credential helper).
4. Check network access to the registry and available disk space; read stderr in the message.

Example fix

# before
ws = AppleContainerWorkspace(base_image="ubunutu:24.04")

# after
ws = AppleContainerWorkspace(base_image="ubuntu:24.04")

# pre-verify the tag resolves before provisioning
import subprocess
r = subprocess.run(["container", "image", "pull", base_image], capture_output=True)
assert r.returncode == 0, f"bad base_image: {base_image}"

try:
    ws = await AppleContainerWorkspace.create(base_image=tag)
except RuntimeError as e:
    if "Failed to pull image" in str(e):
        ws = await AppleContainerWorkspace.create(base_image="ubuntu:24.04")
    else:
        raise

When it happens

Trigger: Creating AppleContainerWorkspace with a base_image that doesn't exist in the registry (typo, wrong tag), registry unreachable, authentication required for a private image, or disk-full preventing the pull.

Common situations: Typos like 'ubunutu:24.04' or nonexistent tags (e.g. 'python:3.99'), air-gapped environments blocking registry access, private registry images without prior `container login`, or low disk space.

Related errors

• not found in container: {path}\nstderr: {result.stderr.decod
• container cp failed (exit {process.returncode}): {stderr.dec
• Apple Container CLI is not installed. Install it first: http
• Apple Container CLI is not available. Ensure it is installed
• Requested path is a directory, not a file.

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