langchain-ai/deepagents · error · WorkspaceConflictError

workspace configuration does not match thread {thread_id}

Error message

workspace configuration does not match thread {thread_id}

What it means

`require_thread_workspace._require` compares the claimed config fingerprint (`canonical_workspace_config(workspace_config)` hash, or the supplied `config_fingerprint`) with the fingerprint persisted at bind time. This `WorkspaceConflictError` means the workspace configuration content changed since the thread was bound, even if the context fields match.

Source

Thrown at libs/code/deepagents_code/workspace.py:369

            _initialize(conn)
            row = conn.execute(
                "SELECT * FROM dcode_thread_workspaces WHERE thread_id = ?",
                (thread_id,),
            ).fetchone()
            if row is None:
                msg = f"thread {thread_id} has no workspace binding"
                raise WorkspaceConflictError(msg)
            existing = _row_binding(row)
            expected = existing.to_payload()
            if any(data.get(key) != value for key, value in expected.items()):
                msg = f"workspace context does not match thread {thread_id}"
                raise WorkspaceConflictError(msg)
            if (
                claimed_fingerprint is not None
                and claimed_fingerprint != existing.config_fingerprint
            ):
                msg = f"workspace configuration does not match thread {thread_id}"
                raise WorkspaceConflictError(msg)
            return existing

    existing = await asyncio.to_thread(_require)
    if existing.schema_version != _SCHEMA_VERSION:
        msg = f"workspace binding schema is unsupported for thread {thread_id}"
        raise WorkspaceConflictError(msg)
    resolved = await asyncio.to_thread(
        resolve_workspace,
        existing.cwd,
        existing.workspace_config(),
        config_fingerprint=existing.config_fingerprint,
    )
    if resolved.workspace_id != existing.workspace_id:
        msg = f"workspace identity changed for thread {thread_id}"
        raise WorkspaceConflictError(msg)
    return existing

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass the exact same workspace_config (or config_fingerprint) used when the thread was bound
2. Start a new thread with the new configuration instead of mutating the bound one
3. If a library upgrade changed canonicalization, re-bind the thread under a fresh id

Example fix

// before
require_thread_workspace(tid, payload=ctx, workspace_config={"policy": "strict"})  # bound with "default"
// after
require_thread_workspace(tid, payload=ctx, workspace_config={"policy": "default"})

claimed_fp, _ = canonical_workspace_config(workspace_config)
stored_fp = binding.config_fingerprint
if claimed_fp != stored_fp:
    raise WorkspaceConflictError("config changed; use a new thread")

try:
    await require_thread_workspace(tid, payload=ctx, workspace_config=cfg)
except WorkspaceConflictError as exc:
    if "configuration does not match" in str(exc):
        tid = new_thread_id()  # new config -> new thread
        await bind_thread_workspace(tid, cwd, workspace_config=cfg)

When it happens

Trigger: Calling `require_thread_workspace` with a `workspace_config` whose canonical JSON differs from the one at bind time, or passing an explicit `config_fingerprint` that does not match the stored one; editing config values (policy, resource settings) between runs of the same thread.

Common situations: Tweaking workspace settings mid-session and re-running the same thread; a key ordering/value normalization change altering the canonical serialization; a library upgrade changing canonicalization; copying a config from another project.

Related errors

• workspace_config must be an object
• workspace configuration is too large
• thread {thread_id} is already bound to a different workspace
• thread {thread_id} has no workspace binding
• workspace context does not match thread {thread_id}

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