agentscope-ai/agentscope · error · ValueError

host_cache_dir must not overlap host_workdir because it is u

Error message

host_cache_dir must not overlap host_workdir because it is used as a Bubblewrap bind source.

What it means

The cache directory is bind-mounted into the Bubblewrap sandbox separately from the workspace; if it overlapped the workspace path, nested/recursive binds would conflict. Realpaths are compared with commonpath and any containment (cache inside workdir or workdir inside cache) is rejected.

Source

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

            self._ensure_cache_directory(
                cache_root,
                make_private=True,
            )
            path = os.path.join(
                cache_root,
                key,
            )
            make_private = True

        if os.path.lexists(path) and os.path.islink(path):
            raise ValueError("host_cache_dir must not be a symbolic link.")
        cache_dir = os.path.realpath(path)
        try:
            common = os.path.commonpath([workdir, cache_dir])
        except ValueError:
            common = ""
        if common in (workdir, cache_dir):
            raise ValueError(
                "host_cache_dir must not overlap host_workdir because it "
                "is used as a Bubblewrap bind source.",
            )

        self._ensure_cache_directory(
            path,
            make_private=make_private,
        )
        return os.path.realpath(path)

    @staticmethod
    def _ensure_cache_directory(
        path: str,
        *,
        make_private: bool,
    ) -> None:
        """Create a cache directory without accepting a symlink root."""
        if os.path.lexists(path) and os.path.islink(path):

View on GitHub (pinned to e90f1c7592)

Solutions

1. Move host_cache_dir completely outside the workspace tree (e.g. ~/.cache/agentscope/<id>)
2. If you intended a private cache, omit host_cache_dir and let the workspace create its own
3. Re-check with os.path.realpath on both paths that they share no commonpath containment

Example fix

# before
ws = BubblewrapWorkspace(host_workdir="/tmp/ws", host_cache_dir="/tmp/ws/cache")
# after
ws = BubblewrapWorkspace(host_workdir="/tmp/ws", host_cache_dir="/tmp/ws-cache")

import os
w, c = os.path.realpath(workdir), os.path.realpath(cache_dir)
if os.path.commonpath([w, c]) in (w, c):
    raise ValueError("cache and workspace overlap")

When it happens

Trigger: host_cache_dir equal to host_workdir, a subdirectory of it, or a parent of it after realpath resolution — including when symlinks made the overlap non-obvious.

Common situations: Setting host_cache_dir to something like <workdir>/cache for convenience; default cache dir resolution colliding with a custom workdir; symlinked paths masking the overlap.

Related errors

• basedir must not be empty.
• BubblewrapWorkspaceManager currently requires share_net=True
• Bubblewrap workdir escapes basedir.
• host_cache_dir must be a directory.
• host_cache_dir was removed or replaced before execution.

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