agentscope-ai/agentscope · error · FileNotFoundError

not found in Bubblewrap sandbox: {path}

Error message

not found in Bubblewrap sandbox: {path}

What it means

read_file executes a shell cat inside the bwrap sandbox and maps exit code 66 to FileNotFoundError. It means the sandboxed process could not find the requested path: the file does not exist inside the container's mounted view.

Source

Thrown at src/agentscope/workspace/_bubblewrap/_bubblewrap_backend.py:270

        sandbox_path = self._sandbox_path_for(path)
        result = await self.exec_shell(
            [
                "sh",
                "-c",
                (
                    'resolved=$(realpath -e -- "$1") || exit 66; '
                    'case "$resolved" in '
                    "/workspace|/workspace/*|/tmp|/tmp/*) "
                    'cat -- "$resolved" ;; '
                    "*) exit 65 ;; "
                    "esac"
                ),
                "sh",
                sandbox_path,
            ],
        )
        if result.exit_code == 66:
            raise FileNotFoundError(f"not found in Bubblewrap sandbox: {path}")
        if result.exit_code == 65:
            raise PermissionError(
                f"path escapes writable Bubblewrap mounts: {path}",
            )
        if not result.ok():
            raise RuntimeError(
                "Bubblewrap read_file failed "
                f"(exit {result.exit_code}): "
                f"{result.stderr.decode(errors='replace')}",
            )
        return result.stdout

    async def write_file(self, path: str, data: bytes) -> None:
        """Write raw bytes, refusing every symbolic-link final component."""
        await self._write_via_cat(path, data)

    async def write_stream(
        self,

View on GitHub (pinned to e90f1c7592)

Solutions

1. Verify the file exists with list_dir/exist checks (or try/except FileNotFoundError) before reading
2. Write the file into the sandbox workspace first
3. Check for typos in absolute sandbox paths — only SANDBOX_WORKDIR and SANDBOX_TMPDIR are visible

Example fix

# before
data = await ws.read_file('/workspace/out.txt')
# after
try:
    data = await ws.read_file('/workspace/out.txt')
except FileNotFoundError:
    data = ''

null

null

try:
    data = await ws.read_file(path)
except FileNotFoundError:
    data = None  # treat as missing

When it happens

Trigger: Calling read_file on a path that was never written, was deleted inside/outside the sandbox, or lives outside the mounted workdir so it is simply absent in the sandbox.

Common situations: Reading a file before the agent created it, referencing a path from the host that was never copied into the workspace, or a race where another process removed the file.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• {left_name} must not overlap {right_name}.
• Bubblewrap read_file failed (exit {result.exit_code}): {resu
• host_workdir must be a directory.
• host_cache_dir must not be a symbolic link.
• not found in OpenSandbox sandbox: {path}

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