langchain-ai/deepagents · error · RuntimeError

Server configuration changed after the workspace was bound.

Error message

Server configuration changed after the workspace was bound.

What it means

RuntimeError raised when the server configuration in effect differs from the configuration fingerprint captured when the thread's workspace was bound. Workspace bindings are keyed to a specific config snapshot; silently applying a changed config could point the thread at different workspace paths, so the runtime rejects it.

Source

Thrown at libs/code/deepagents_code/server_graph.py:584

    if runtime is not None:
        _workspace_runtimes.move_to_end(binding.resource_key)
        return runtime
    lock = _workspace_runtime_locks.setdefault(binding.resource_key, asyncio.Lock())
    async with lock:
        runtime = _workspace_runtimes.get(binding.resource_key)
        if runtime is None:
            config = ServerConfig.from_env()
            current_config = dataclasses.replace(
                config,
                cwd=binding.cwd,
                project_root=binding.project_root,
            )
            if (
                current_config.workspace_fingerprint() != binding.config_fingerprint
                or current_config.to_workspace_payload() != binding.workspace_config()
            ):
                msg = "Server configuration changed after the workspace was bound."
                raise RuntimeError(msg)
            config = current_config
            project_context = ProjectContext(
                user_cwd=Path(binding.cwd),
                project_root=Path(binding.project_root)
                if binding.project_root
                else None,
            )
            runtime = await _make_graphs(
                config_override=config,
                project_context_override=project_context,
            )
            _workspace_runtimes[binding.resource_key] = runtime
            if len(_workspace_runtimes) > _MAX_WORKSPACE_RUNTIMES:
                evicted_key, _ = _workspace_runtimes.popitem(last=False)
                _workspace_runtime_locks.pop(evicted_key, None)
    return runtime

View on GitHub (pinned to a1af029e6e)

Solutions

1. Rebind the thread's workspace under the new configuration (clear/recreate the binding), then retry
2. Revert the config change so it matches the fingerprint at bind time
3. Restart the session/thread so binding and config are captured together
4. Keep workspace-related config immutable for the lifetime of a bound thread

Example fix

// before
# config edited after thread bound
agent = await make_graph(config_with_thread, current_mutated_config)

// after
# rebind workspace with the new config first, then execute
await rebind_thread_workspace(thread_id, new_config)
agent = await make_graph(config_with_thread, new_config)

from deepagents_code.server_graph import current_workspace_fingerprint
binding = get_thread_binding(thread_id)
if binding and current_config.workspace_fingerprint() != binding.config_fingerprint:
    rebind_thread_workspace(thread_id, current_config)  # rebind before executing

try:
    agent = await make_graph(config, server_config)
except RuntimeError as e:
    if "configuration changed" in str(e):
        await rebind_thread_workspace(thread_id, server_config)
        agent = await make_graph(config, server_config)
    else:
        raise

When it happens

Trigger: Calling make_graph (via _workspace_runtime) for a thread whose binding exists but whose current config's workspace_fingerprint() or to_workspace_payload() no longer match the bound values — i.e. config was edited/overridden between binding and execution.

Common situations: Editing server/workspace config (paths, workspace settings) while a session is live; different processes or reloads using divergent configs for the same thread id; test setups that mutate config after binding (see test_rejects_server_config_drift).

Related errors

• RemoteAgent workspace is not configured.
• Workspace policy and fingerprint must be configured together
• {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/7611ab00b1c8c5c6. Report an issue: GitHub.