agentscope-ai/agentscope · error · RuntimeError

BubblewrapWorkspace requires 'bwrap' on PATH.

Error message

BubblewrapWorkspace requires 'bwrap' on PATH.

What it means

The workspace shells out to the bwrap binary, so provisioning verifies it exists on PATH via shutil.which. If bwrap is not installed (or not visible to the Python process), startup fails with this RuntimeError.

Source

Thrown at src/agentscope/workspace/_bubblewrap/_bubblewrap_workspace.py:195

            isinstance(gateway_port, bool)
            or not isinstance(gateway_port, int)
            or not 1 <= gateway_port <= 65535
        ):
            raise ValueError(
                "gateway_port must be None or an integer from 1 to 65535.",
            )

    @property
    def is_persistent(self) -> bool:
        """Whether the workspace files survive ``close``."""
        return self._host_workdir_input is not None

    async def _provision_backend(self) -> None:
        """Validate Bubblewrap availability and bind the backend."""
        if not sys.platform.startswith("linux"):
            raise RuntimeError("BubblewrapWorkspace requires Linux.")
        if shutil.which("bwrap") is None:
            raise RuntimeError("BubblewrapWorkspace requires 'bwrap' on PATH.")
        await self._probe_bubblewrap()
        if self._host_workdir_input is None:
            self._owned_workdir = tempfile.TemporaryDirectory()
            self.host_workdir = self._owned_workdir.name
        else:
            self.host_workdir = os.path.abspath(self._host_workdir_input)
        workdir_created = not os.path.lexists(self.host_workdir)
        os.makedirs(self.host_workdir, mode=0o700, exist_ok=True)
        if not os.path.isdir(self.host_workdir):
            raise ValueError("host_workdir must be a directory.")
        if workdir_created:
            os.chmod(self.host_workdir, 0o700)

        if (
            self._host_workdir_input is None
            and self._host_cache_dir_input is None
        ):
            self._owned_cache_dir = tempfile.TemporaryDirectory(

View on GitHub (pinned to e90f1c7592)

Solutions

1. Install bubblewrap: apt-get install -y bubblewrap (Debian/Ubuntu) or dnf install bubblewrap, then restart the process
2. In Dockerfiles add the package in the same image the app runs in
3. Verify with shutil.which('bwrap') before starting and fall back to another workspace backend

Example fix

# Dockerfile before
FROM python:3.12-slim
RUN pip install agentscope
# Dockerfile after
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends bubblewrap && rm -rf /var/lib/apt/lists/*
RUN pip install agentscope

import shutil
assert shutil.which('bwrap') is not None, 'install bubblewrap (apt-get install bubblewrap)'

def bwrap_available() -> bool:
    import shutil
    return shutil.which('bwrap') is not None

try:
    ws = BubblewrapWorkspace(...)
except RuntimeError as e:
    if 'bwrap' in str(e):
        ws = LocalWorkspace(...)  # fallback backend

When it happens

Trigger: Starting BubblewrapWorkspace on a host without the bubblewrap package installed, in a slim Docker image, or in an env where PATH omits /usr/bin.

Common situations: Minimal container images (python:3-slim) lacking bubblewrap; macOS/WSL hosts without the package; PATH overridden by a service manager or venv activation script.

Related errors

• basedir must not be empty.
• BubblewrapWorkspaceManager currently requires share_net=True
• Bubblewrap workdir escapes basedir.
• workspace_id {workspace_id!r} escapes the workspace base dir
• {left_name} must not overlap {right_name}.

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