{"record":{"id":"dd30fed7ca3b4883","repo":"langchain-ai/deepagents","slug":"remoteagent-workspace-is-not-configured","errorCode":null,"errorMessage":"RemoteAgent workspace is not configured.","messagePattern":"RemoteAgent workspace is not configured\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/client/remote_client.py","lineNumber":801,"sourceCode":"                \"Failed to write store item %s/%s\",\n                \".\".join(namespace),\n                key,\n                exc_info=True,\n            )\n            # Load-bearing: see Notes. Callers fail closed on this propagation.\n            raise\n\n    async def _workspace_for_thread(\n        self,\n        config: Mapping[str, Any],\n    ) -> dict[str, Any]:\n        thread_id = _require_thread_id(config)\n        workspace = self._workspaces.get(thread_id)\n        if workspace is not None:\n            return workspace\n        if self._workspace_cwd is None:\n            msg = \"RemoteAgent workspace is not configured.\"\n            raise RuntimeError(msg)\n        return await self.abind_workspace(config, self._workspace_cwd)\n\n    async def abind_workspace(\n        self, config: Mapping[str, Any], cwd: str\n    ) -> dict[str, Any]:\n        \"\"\"Create or verify the remote thread's durable workspace binding.\n\n        Returns:\n            The server-validated workspace descriptor.\n\n        Raises:\n            TypeError: If the server returns a malformed descriptor.\n        \"\"\"\n        thread_id = _require_thread_id(config)\n        graph = self._get_graph()\n        payload: dict[str, Any] = {\"cwd\": cwd}\n        if self._workspace_config is not None:\n            payload[\"workspace_config\"] = self._workspace_config","sourceCodeStart":783,"sourceCodeEnd":819,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/remote_client.py#L783-L819","documentation":"`_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.","triggerScenarios":"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`).","commonSituations":"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.","solutions":["Call `agent.set_workspace(cwd)` (optionally with `config` and `config_fingerprint`) before your first `aoffload`/`astream`.","Use the application's normal client-construction path (`_configure_remote_agent` / `start_server_and_get_agent`), which configures the workspace automatically.","If you bind workspaces per-thread explicitly, call `abind_workspace(config, cwd)` first so `_workspaces` is populated for that thread.","Verify you are operating on the same RemoteAgent instance that had the workspace set — a second instance starts with no configuration."],"exampleFix":"// before\nagent = RemoteAgent(url)\nawait agent.astream(input, config=config)  # RuntimeError\n\n// after\nagent = RemoteAgent(url)\nagent.set_workspace(\"/path/to/project\")\nawait agent.astream(input, config=config)","handlingStrategy":"validation","validationCode":"if getattr(agent, \"_workspace_cwd\", None) is None and not getattr(agent, \"_workspaces\", None):\n    raise RuntimeError(\"Call set_workspace(cwd) on the RemoteAgent before streaming/offloading\")","typeGuard":null,"tryCatchPattern":"try:\n    await agent.astream(input, config=config)\nexcept RuntimeError as exc:\n    if \"workspace is not configured\" in str(exc):\n        agent.set_workspace(project_root)\n        await agent.astream(input, config=config)\n    else:\n        raise","preventionTips":["Always call `set_workspace(cwd)` immediately after constructing a RemoteAgent.","Prefer the app's standard construction path (`_configure_remote_agent`) over hand-built instances.","In tests, use a fixture that configures the workspace for every client."],"tags":["configuration","workspace","setup","remote-agent"],"backgroundTag":"missing-config-key","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}