{"record":{"id":"21c08f034ea04016","repo":"langchain-ai/deepagents","slug":"a-workspace-is-required-to-start-the-remote-agent","errorCode":null,"errorMessage":"A workspace is required to start the remote agent.","messagePattern":"A workspace is required to start the remote agent\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/client/launch/server_manager.py","lineNumber":454,"sourceCode":"\n    server = ServerProcess(\n        host=host,\n        port=port,\n        config_dir=work_dir,\n        owns_config_dir=True,\n        scaffold=_scaffold_workspace,\n    )\n    started = False\n    try:\n        await server.start()\n        await server.wait_for_graph_ready(\"agent\")\n        agent = RemoteAgent(\n            url=server.url,\n            graph_name=\"agent\",\n        )\n        if project_context is None:\n            msg = \"A workspace is required to start the remote agent.\"\n            raise RuntimeError(msg)\n        agent.set_workspace(\n            str(project_context.user_cwd),\n            config.to_workspace_payload(),\n            config_fingerprint=config.workspace_fingerprint(),\n        )\n        started = True\n        return agent, server, None\n    finally:\n        if not started:\n            # Startup failed or was cancelled before the server was handed off\n            # to the caller (which records the reference only on success). If\n            # `start()` itself failed it already reaped its own subprocess, so\n            # this `stop()` is then an idempotent no-op; this cleanup is the sole\n            # reaper only when `start()` succeeded but `wait_for_graph_ready()`\n            # (or `RemoteAgent()`) failed afterward. A `finally` rather than\n            # `except Exception` is deliberate: `asyncio.CancelledError` is a\n            # `BaseException`, so an `except Exception` guard would skip cleanup\n            # and orphan the process. The inner guard stops a `stop()` error","sourceCodeStart":436,"sourceCodeEnd":472,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/client/launch/server_manager.py#L436-L472","documentation":"At the end of `start_server_and_get_agent`, the returned RemoteAgent requires a workspace: `set_workspace` is called with the project context's user cwd, workspace payload, and fingerprint. If `project_context` is None at that point, this RuntimeError is raised — a remote agent cannot operate without a working directory bound to it.","triggerScenarios":"Calling `start_server_and_get_agent` (directly or via `_start_server_background`, `_replace_server_after_cwd_switch`, or `server_session`) in a code path where no project/workspace context was resolved — e.g. launching outside any recognized project with workspace resolution disabled, or a caller that explicitly passes project_context=None.","commonSituations":"Running the agent from an environment with no workspace attached; custom integrations that invoke the server manager without constructing a project context; a cwd-switch flow that failed to resolve the new project context before replacing the server.","solutions":["Ensure a project context is resolved before starting the server (open/attach a workspace first)","If calling the manager API directly, pass or construct a valid project_context instead of None","Fix the cwd-switch flow to resolve the new project context before calling `_replace_server_after_cwd_switch`","Run the agent from a directory that workspace detection recognizes so a context is produced"],"exampleFix":"// before\nagent = await start_server_and_get_agent(..., project_context=None)  # RuntimeError\n// after\nctx = resolve_project_context(cwd)\nagent = await start_server_and_get_agent(..., project_context=ctx)","handlingStrategy":"validation","validationCode":"if project_context is None or not getattr(project_context, \"user_cwd\", None):\n    raise RuntimeError(\"resolve a project context before starting the remote agent\")","typeGuard":"def has_workspace(ctx) -> bool:\n    return ctx is not None and bool(getattr(ctx, \"user_cwd\", None))","tryCatchPattern":"try:\n    agent = await start_server_and_get_agent(..., project_context=ctx)\nexcept RuntimeError as e:\n    if \"workspace is required\" in str(e):\n        ctx = resolve_project_context(Path.cwd())\n        agent = await start_server_and_get_agent(..., project_context=ctx)\n    else:\n        raise","preventionTips":["Always resolve project context before server startup","Never pass project_context=None through wrapper layers","In cwd-switch flows, resolve the new context before replacing the server"],"tags":["workspace","lifecycle","runtime-error"],"backgroundTag":"missing-workspace","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}