agentscope-ai/agentscope · error · ValueError

basedir must not be empty.

Error message

basedir must not be empty.

What it means

BubblewrapWorkspaceManager.__init__ rejects an empty (or whitespace-only) basedir because every sandboxed workspace is created underneath it and an empty path is meaningless/unsafe.

Source

Thrown at src/agentscope/app/workspace_manager/_bubblewrap_workspace_manager.py:81

                allocate an available loopback port during initialization.
            share_net (`bool`, defaults to `True`):
                Must be ``True`` for the current Bubblewrap workspace TCP
                gateway design.
            env (`dict[str, str] | None`, optional):
                Extra environment variables for every workspace.
            extra_pip (`list[str] | None`, optional):
                Extra gateway venv requirements.
            default_mcps (`list[MCPClient] | None`, optional):
                MCPs seeded into new workspaces.
            skill_paths (`list[str] | None`, optional):
                Skill dirs seeded into new workspaces.
            ttl (`float`, defaults to `3600.0`):
                Seconds before an idle workspace is evicted.
            sweep_interval (`float`, defaults to `300.0`):
                Seconds between sweeper ticks.
        """
        if not basedir.strip():
            raise ValueError("basedir must not be empty.")
        BubblewrapWorkspace._validate_gateway_port(gateway_port)
        if not share_net:
            raise ValueError(
                "BubblewrapWorkspaceManager currently requires "
                "share_net=True because BubblewrapWorkspace uses a TCP MCP "
                "gateway across separate bwrap executions.",
            )

        self._basedir = os.path.abspath(basedir)
        self._gateway_port = gateway_port
        self._share_net = share_net
        self._env = dict(env or {})
        self._extra_pip = list(extra_pip or [])
        self._default_mcps = list(default_mcps or [])
        self._skill_paths = list(skill_paths or [])
        self._ttl = ttl
        self._sweep_interval = sweep_interval
        super().__init__(isolation=isolation)

View on GitHub (pinned to e90f1c7592)

Solutions

1. Pass a non-empty absolute directory path such as /var/lib/agent/workspaces
2. If basedir comes from config, add a startup check with a sensible default
3. Fail fast at app boot with a clear message instead of at manager construction

Example fix

# before
mgr = BubblewrapWorkspaceManager(basedir=os.getenv("WS_DIR", ""))
# after
basedir = os.getenv("WS_DIR") or "/var/lib/agent/workspaces"
mgr = BubblewrapWorkspaceManager(basedir=basedir)

basedir = os.getenv(\"WS_BASEDIR\") or \"/var/lib/agent/workspaces\"\nassert basedir.strip(), \"basedir must be configured\"

When it happens

Trigger: Instantiating BubblewrapWorkspaceManager(basedir="") or basedir=" "; commonly when basedir comes from an env var or config key that was never set (defaulting to empty string).

Common situations: Missing WORKSPACE_BASEDIR-style env var; config file with an empty basedir field; default parameter changed to '' in a refactor.

Related errors

• BubblewrapWorkspaceManager currently requires share_net=True
• Bubblewrap workdir escapes basedir.
• dimensions is required: pass it explicitly to EmbeddingModel
• {left_name} must not overlap {right_name}.
• BubblewrapWorkspace currently requires share_net=True becaus

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