agentscope-ai/agentscope · error · ValueError

host_cache_dir must not be empty.

Error message

host_cache_dir must not be empty.

What it means

host_cache_dir, like host_workdir, must be a non-empty string when provided. An empty or whitespace-only value cannot be bind-mounted as the sandbox cache and is rejected at construction.

Source

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

                invalidate an existing Bootstrap environment.
            instructions (`str`, optional):
                System-prompt fragment template.
            default_mcps (`list[MCPClient] | None`, optional):
                MCPs seeded on first initialization.
            skill_paths (`list[str] | None`, optional):
                Local skill directories seeded on first initialization.
        """
        self._validate_gateway_port(gateway_port)
        if not share_net:
            raise ValueError(
                "BubblewrapWorkspace currently requires share_net=True "
                "because its TCP MCP gateway must be reachable across "
                "separate bwrap executions.",
            )
        if host_workdir is not None and not host_workdir.strip():
            raise ValueError("host_workdir must not be empty.")
        if host_cache_dir is not None and not host_cache_dir.strip():
            raise ValueError("host_cache_dir must not be empty.")

        super().__init__(
            workspace_id=workspace_id,
            default_mcps=default_mcps,
            skill_paths=skill_paths,
        )

        self.workdir = SANDBOX_WORKDIR
        self.gateway_port = gateway_port
        self._gateway_port_input = gateway_port
        self._gateway_token = ""
        self._gateway_nonce = ""
        self._rotate_gateway_credentials()
        self.share_net = share_net
        self.env = dict(env or {})
        self.extra_pip = list(extra_pip or [])
        self.instructions = instructions

View on GitHub (pinned to e90f1c7592)

Solutions

1. Pass None instead of an empty string when no cache dir is wanted
2. Normalize inputs: cache = cfg.get('host_cache_dir') or None

Example fix

# before
ws = BubblewrapWorkspace(host_cache_dir=cfg['cache_dir'])  # '' when unset
# after
ws = BubblewrapWorkspace(host_cache_dir=cfg.get('host_cache_dir') or None)

host_cache_dir = cfg.get('host_cache_dir') or None

def non_empty_or_none(v: str | None) -> str | None:
    return v.strip() or None if isinstance(v, str) else None

null

When it happens

Trigger: BubblewrapWorkspace(host_cache_dir='') or ' ', typically from optional config fields left blank.

Common situations: Serialized config where an optional cache path round-trips as '' instead of null; UI forms submitting empty strings.

Related errors

• host_workdir must not be empty.
• gateway_port must be None or an integer from 1 to 65535.
• The injection template must contain the '{runtime_state}' pl
• MCP {card.name!r} produced an invalid client: {e}
• DimensionPolicy: kind=ANY requires dimension=None, got dimen

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