langchain-ai/deepagents · error · RuntimeError

RemoteAgent workspace is not configured.

Error message

RemoteAgent workspace is not configured.

What it means

`_workspace_for_thread` resolves the per-thread workspace descriptor: first from the `_workspaces` cache, otherwise by binding `self._workspace_cwd` server-side. If no cached binding exists and the client was never given a workspace cwd via `set_workspace`/`_configure_remote_agent`, it raises this RuntimeError. Offload and stream operations need the workspace to tell the server which filesystem the thread operates on.

Source

Thrown at libs/code/deepagents_code/client/remote_client.py:801

                "Failed to write store item %s/%s",
                ".".join(namespace),
                key,
                exc_info=True,
            )
            # Load-bearing: see Notes. Callers fail closed on this propagation.
            raise

    async def _workspace_for_thread(
        self,
        config: Mapping[str, Any],
    ) -> dict[str, Any]:
        thread_id = _require_thread_id(config)
        workspace = self._workspaces.get(thread_id)
        if workspace is not None:
            return workspace
        if self._workspace_cwd is None:
            msg = "RemoteAgent workspace is not configured."
            raise RuntimeError(msg)
        return await self.abind_workspace(config, self._workspace_cwd)

    async def abind_workspace(
        self, config: Mapping[str, Any], cwd: str
    ) -> dict[str, Any]:
        """Create or verify the remote thread's durable workspace binding.

        Returns:
            The server-validated workspace descriptor.

        Raises:
            TypeError: If the server returns a malformed descriptor.
        """
        thread_id = _require_thread_id(config)
        graph = self._get_graph()
        payload: dict[str, Any] = {"cwd": cwd}
        if self._workspace_config is not None:
            payload["workspace_config"] = self._workspace_config

View on GitHub (pinned to a1af029e6e)

Solutions

1. Call `agent.set_workspace(cwd)` (optionally with `config` and `config_fingerprint`) before your first `aoffload`/`astream`.
2. Use the application's normal client-construction path (`_configure_remote_agent` / `start_server_and_get_agent`), which configures the workspace automatically.
3. If you bind workspaces per-thread explicitly, call `abind_workspace(config, cwd)` first so `_workspaces` is populated for that thread.
4. Verify you are operating on the same RemoteAgent instance that had the workspace set — a second instance starts with no configuration.

Example fix

// before
agent = RemoteAgent(url)
await agent.astream(input, config=config)  # RuntimeError

// after
agent = RemoteAgent(url)
agent.set_workspace("/path/to/project")
await agent.astream(input, config=config)

if getattr(agent, "_workspace_cwd", None) is None and not getattr(agent, "_workspaces", None):
    raise RuntimeError("Call set_workspace(cwd) on the RemoteAgent before streaming/offloading")

try:
    await agent.astream(input, config=config)
except RuntimeError as exc:
    if "workspace is not configured" in str(exc):
        agent.set_workspace(project_root)
        await agent.astream(input, config=config)
    else:
        raise

When it happens

Trigger: Calling `aoffload` or `astream` on a RemoteAgent constructed directly (`RemoteAgent(url)`) without ever calling `set_workspace(cwd)`, for a thread that has no cached binding (first use, or after `set_workspace` cleared `_workspaces`).

Common situations: Instantiating `RemoteAgent` manually in a script or test instead of through the app's `_configure_remote_agent`, which sets the workspace; constructing the client, calling `set_workspace`, then having it fail later because bindings were cleared and cwd is somehow None again (shouldn't happen) — most commonly just forgetting `set_workspace` entirely.

Related errors

• Workspace policy and fingerprint must be configured together
• Server configuration changed after the workspace was bound.
• {what} must be absolute: {path}
• Could not determine the home directory: set $HOME, or set DE
• Home directory is not absolute: {launch_home}. Set $HOME to

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/dd30fed7ca3b4883. Report an issue: GitHub.