{"record":{"id":"dfddc2f507296415","repo":"agentscope-ai/agentscope","slug":"bubblewrapworkspace-requires-bwrap-on-path","errorCode":null,"errorMessage":"BubblewrapWorkspace requires 'bwrap' on PATH.","messagePattern":"BubblewrapWorkspace requires 'bwrap' on PATH\\.","errorType":"error_code","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/agentscope/workspace/_bubblewrap/_bubblewrap_workspace.py","lineNumber":195,"sourceCode":"            isinstance(gateway_port, bool)\n            or not isinstance(gateway_port, int)\n            or not 1 <= gateway_port <= 65535\n        ):\n            raise ValueError(\n                \"gateway_port must be None or an integer from 1 to 65535.\",\n            )\n\n    @property\n    def is_persistent(self) -> bool:\n        \"\"\"Whether the workspace files survive ``close``.\"\"\"\n        return self._host_workdir_input is not None\n\n    async def _provision_backend(self) -> None:\n        \"\"\"Validate Bubblewrap availability and bind the backend.\"\"\"\n        if not sys.platform.startswith(\"linux\"):\n            raise RuntimeError(\"BubblewrapWorkspace requires Linux.\")\n        if shutil.which(\"bwrap\") is None:\n            raise RuntimeError(\"BubblewrapWorkspace requires 'bwrap' on PATH.\")\n        await self._probe_bubblewrap()\n        if self._host_workdir_input is None:\n            self._owned_workdir = tempfile.TemporaryDirectory()\n            self.host_workdir = self._owned_workdir.name\n        else:\n            self.host_workdir = os.path.abspath(self._host_workdir_input)\n        workdir_created = not os.path.lexists(self.host_workdir)\n        os.makedirs(self.host_workdir, mode=0o700, exist_ok=True)\n        if not os.path.isdir(self.host_workdir):\n            raise ValueError(\"host_workdir must be a directory.\")\n        if workdir_created:\n            os.chmod(self.host_workdir, 0o700)\n\n        if (\n            self._host_workdir_input is None\n            and self._host_cache_dir_input is None\n        ):\n            self._owned_cache_dir = tempfile.TemporaryDirectory(","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/workspace/_bubblewrap/_bubblewrap_workspace.py#L177-L213","documentation":"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.","triggerScenarios":"Starting BubblewrapWorkspace on a host without the bubblewrap package installed, in a slim Docker image, or in an env where PATH omits /usr/bin.","commonSituations":"Minimal container images (python:3-slim) lacking bubblewrap; macOS/WSL hosts without the package; PATH overridden by a service manager or venv activation script.","solutions":["Install bubblewrap: apt-get install -y bubblewrap (Debian/Ubuntu) or dnf install bubblewrap, then restart the process","In Dockerfiles add the package in the same image the app runs in","Verify with shutil.which('bwrap') before starting and fall back to another workspace backend"],"exampleFix":"# Dockerfile before\nFROM python:3.12-slim\nRUN pip install agentscope\n# Dockerfile after\nFROM python:3.12-slim\nRUN apt-get update && apt-get install -y --no-install-recommends bubblewrap && rm -rf /var/lib/apt/lists/*\nRUN pip install agentscope","handlingStrategy":"validation","validationCode":"import shutil\nassert shutil.which('bwrap') is not None, 'install bubblewrap (apt-get install bubblewrap)'","typeGuard":"def bwrap_available() -> bool:\n    import shutil\n    return shutil.which('bwrap') is not None","tryCatchPattern":"try:\n    ws = BubblewrapWorkspace(...)\nexcept RuntimeError as e:\n    if 'bwrap' in str(e):\n        ws = LocalWorkspace(...)  # fallback backend","preventionTips":["Add bubblewrap to Dockerfiles/CI images","Health-check shutil.which('bwrap') at startup and fall back gracefully"],"tags":["bubblewrap","missing-binary","environment","docker"],"backgroundTag":"missing-executable-on-path","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}