langchain-ai/deepagents · error · RuntimeError

A workspace is required to start the remote agent.

Error message

A workspace is required to start the remote agent.

What it means

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.

Source

Thrown at libs/code/deepagents_code/client/launch/server_manager.py:454

    server = ServerProcess(
        host=host,
        port=port,
        config_dir=work_dir,
        owns_config_dir=True,
        scaffold=_scaffold_workspace,
    )
    started = False
    try:
        await server.start()
        await server.wait_for_graph_ready("agent")
        agent = RemoteAgent(
            url=server.url,
            graph_name="agent",
        )
        if project_context is None:
            msg = "A workspace is required to start the remote agent."
            raise RuntimeError(msg)
        agent.set_workspace(
            str(project_context.user_cwd),
            config.to_workspace_payload(),
            config_fingerprint=config.workspace_fingerprint(),
        )
        started = True
        return agent, server, None
    finally:
        if not started:
            # Startup failed or was cancelled before the server was handed off
            # to the caller (which records the reference only on success). If
            # `start()` itself failed it already reaped its own subprocess, so
            # this `stop()` is then an idempotent no-op; this cleanup is the sole
            # reaper only when `start()` succeeded but `wait_for_graph_ready()`
            # (or `RemoteAgent()`) failed afterward. A `finally` rather than
            # `except Exception` is deliberate: `asyncio.CancelledError` is a
            # `BaseException`, so an `except Exception` guard would skip cleanup
            # and orphan the process. The inner guard stops a `stop()` error

View on GitHub (pinned to a1af029e6e)

Solutions

  1. Ensure a project context is resolved before starting the server (open/attach a workspace first)
  2. If calling the manager API directly, pass or construct a valid project_context instead of None
  3. Fix the cwd-switch flow to resolve the new project context before calling `_replace_server_after_cwd_switch`
  4. Run the agent from a directory that workspace detection recognizes so a context is produced

Example fix

// before
agent = await start_server_and_get_agent(..., project_context=None)  # RuntimeError
// after
ctx = resolve_project_context(cwd)
agent = await start_server_and_get_agent(..., project_context=ctx)
Defensive patterns

Strategy: validation

Validate before calling

if project_context is None or not getattr(project_context, "user_cwd", None):
    raise RuntimeError("resolve a project context before starting the remote agent")

Type guard

def has_workspace(ctx) -> bool:
    return ctx is not None and bool(getattr(ctx, "user_cwd", None))

Try / catch

try:
    agent = await start_server_and_get_agent(..., project_context=ctx)
except RuntimeError as e:
    if "workspace is required" in str(e):
        ctx = resolve_project_context(Path.cwd())
        agent = await start_server_and_get_agent(..., project_context=ctx)
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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