agentscope-ai/agentscope · error · ValueError

host_cache_dir must be a real directory.

Error message

host_cache_dir must be a real directory.

What it means

After makedirs, the cache path is re-validated to be a real directory (not a link, isdir true). It fires when creation raced with something replacing the path, or when the path existed as a non-directory and makedirs(exist_ok=True) did not convert it.

Source

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

        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):
            raise ValueError("host_cache_dir must not be a symbolic link.")
        created = not os.path.lexists(path)
        os.makedirs(path, mode=0o700, exist_ok=True)
        if os.path.islink(path) or not os.path.isdir(path):
            raise ValueError("host_cache_dir must be a real directory.")
        if created or make_private:
            os.chmod(path, 0o700)

    async def initialize(self) -> None:
        """Initialize and clean up partial resources on failure."""
        try:
            await super().initialize()
        except BaseException:
            try:
                await asyncio.shield(self.close())
            except BaseException:
                logger.exception(
                    "Bubblewrap cleanup after init failure failed",
                )
            raise

    async def _teardown_backend(self) -> None:
        """Terminate the gateway process and clean ephemeral directories."""

View on GitHub (pinned to e90f1c7592)

Solutions

1. Inspect and clear the offending path: rm the file at host_cache_dir
2. Choose a different host_cache_dir location
3. Ensure no other process mutates the cache path during provisioning

Example fix

# before
# ~/.cache/agentscope exists as a plain file
# after
import os, shutil
p = os.path.expanduser("~/.cache/agentscope")
if os.path.lexists(p) and not os.path.isdir(p):
    os.remove(p)
ws = BubblewrapWorkspace(...)

import os
p = os.path.realpath(os.path.expanduser(cache_dir))
if os.path.lexists(p) and not os.path.isdir(p):
    raise ValueError(f"{p} exists but is not a directory")

When it happens

Trigger: host_cache_dir exists as a regular file; a dangling symlink replaced between checks; a race where another process swaps the path.

Common situations: Leftover cache-marker file at the cache path; tools that create a file where the workspace expects a directory; NFS/FUSE oddities where isdir is false.

Related errors

• host_cache_dir must be a directory.
• host_workdir must be a directory.
• host_cache_dir must not be a symbolic link.
• Path {path_file} exists but is not a file.
• File {path_file} does not exist.

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