agentscope-ai/agentscope · warning · FileNotFoundError

not found in OpenSandbox sandbox: {path}

Error message

not found in OpenSandbox sandbox: {path}

What it means

Raised by OpenSandboxBackend.read_file when the remote sandbox reports a missing file. OpenSandbox surfaces 404s through the HTTP transport (httpx.HTTPStatusError); the backend detects it via _is_not_found_error and re-raises as the standard Python FileNotFoundError with a path-qualified message, so callers get idiomatic not-found semantics.

Source

Thrown at src/agentscope/workspace/_opensandbox/_opensandbox_backend.py:138

        Returns:
            `bytes`:
                The raw file contents.

        Raises:
            `FileNotFoundError`:
                If the path does not exist inside the sandbox.
        """
        try:
            data = await self._sandbox.files.read_bytes(path)
        except FileNotFoundError:
            raise
        except Exception as exc:  # noqa: BLE001
            # OpenSandbox surfaces missing files through the HTTP
            # transport today (httpx.HTTPStatusError with a 404
            # response). Keep a message fallback for SDK wrappers that
            # do not expose the response object.
            if self._is_not_found_error(exc):
                raise FileNotFoundError(
                    f"not found in OpenSandbox sandbox: {path}",
                ) from exc
            raise
        return data

    async def write_file(self, path: str, data: bytes) -> None:
        """Write raw bytes to a file inside the sandbox.

        Creates parent directories via ``exec_shell`` first.

        Args:
            path (`str`):
                Destination path inside the sandbox.
            data (`bytes`):
                The raw bytes to write.
        """
        parent = posixpath.dirname(path)
        if parent:

View on GitHub (pinned to e90f1c7592)

Solutions

1. Verify the path: list the parent directory in the sandbox before reading.
2. Create the file (or run the command that produces it) before read_file.
3. Catch FileNotFoundError and treat as 'not produced yet' in polling loops.
4. If the sandbox was recycled, re-run setup steps that materialize the file.

Example fix

# before
data = await backend.read_file("/workspace/out.txt")  # FileNotFoundError

# after
try:
    data = await backend.read_file("/workspace/out.txt")
except FileNotFoundError:
    await backend.run_command("touch /workspace/out.txt")
    data = await backend.read_file("/workspace/out.txt")

try:
    entries = await backend.list_dir(str(PurePosixPath(path).parent))
    exists = PurePosixPath(path).name in entries
except Exception:
    exists = False

try:
    data = await backend.read_file(path)
except FileNotFoundError:
    data = None  # treat as not-yet-produced

When it happens

Trigger: await backend.read_file(path) where the file does not exist in the sandbox: reading output paths before the agent created them, wrong relative/absolute path, or reading after the sandbox was reset.

Common situations: Assuming a file exists after running a command that silently failed, path mismatches (leading '/', cwd differences between local and sandbox), or sandbox ephemeral storage wiped between calls.

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

• not found in Bubblewrap sandbox: {path}
• One or more tool calls raised an exception
• Input validation failed for tool '{tool_call.name}': {e.mess
• Invalid permission decision behavior: {decision.behavior}
• Model call failed after retries, but no exception was raised

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