agentscope-ai/agentscope · error · ValueError

Sandbox path must be absolute: {path!r}

Error message

Sandbox path must be absolute: {path!r}

What it means

_sandbox_path_for normalizes every path used for sandbox reads/writes and requires it to be absolute. Relative paths are ambiguous inside the container (whose CWD differs from the host), so the API rejects them immediately with ValueError.

Source

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

            "/etc/group",
        ):
            if os.path.exists(path):
                args.extend(["--ro-bind", path, path])
        for path in (
            "/etc/alternatives",
            "/etc/ssl",
            "/etc/pki",
            "/etc/ca-certificates",
        ):
            if os.path.exists(path):
                args.extend(["--ro-bind", path, path])
        return args

    def _sandbox_path_for(self, path: str) -> str:
        """Validate and normalize a writable sandbox path."""
        sandbox_path = PurePosixPath(path)
        if not sandbox_path.is_absolute():
            raise ValueError(f"Sandbox path must be absolute: {path!r}")

        normalized = posixpath.normpath(path)
        for sandbox_root in (SANDBOX_WORKDIR, SANDBOX_TMPDIR):
            if normalized == sandbox_root:
                return normalized
            prefix = sandbox_root + "/"
            if normalized.startswith(prefix):
                return normalized

        raise PermissionError(
            "Bubblewrap file access is limited to "
            f"{SANDBOX_WORKDIR!r} and {SANDBOX_TMPDIR!r}: {path!r}",
        )

View on GitHub (pinned to e90f1c7592)

Solutions

1. Prefix relative names with the sandbox workdir constant to build an absolute path
2. Use PurePosixPath(workdir) / name to join safely
3. Validate paths are absolute before calling the API

Example fix

# before
await ws.read_file('results.json')
# after
await ws.read_file('/workspace/results.json')

assert PurePosixPath(path).is_absolute(), f'need absolute sandbox path: {path}'

def is_absolute_sandbox_path(p: str) -> bool:
    return PurePosixPath(p).is_absolute()

except ValueError as e:
    if 'must be absolute' in str(e):
        path = str(PurePosixPath('/workspace') / path); retry

When it happens

Trigger: Calling read_file/write_file with 'out.txt', './data.csv', or any path not starting with '/'.

Common situations: Porting host-side code that used relative paths with os.getcwd(); concatenating a bare filename onto an API that expects a full sandbox path.

Related errors

• host_workdir must not be empty.
• host_cache_dir must not be empty.
• gateway_port must be None or an integer from 1 to 65535.
• Invalid logging level: {level}. Must be one of 'INFO', 'DEBU
• The 'reserve_ratio' of the context config must be smaller th

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