langchain-ai/deepagents · error · RuntimeError

This server does not provide dcode's /offload operation. Use

Error message

This server does not provide dcode's /offload operation. Use the built-in dcode server, or upgrade the server to a version that registers it.

What it means

`aoffload` POSTs to the dcode-specific route `/dcode/threads/{thread_id}/offload`. When the server answers 404 (`langgraph_sdk.errors.NotFoundError`), the client re-raises it as this RuntimeError because the bare SDK 404 names neither the cause nor the fix. The route only exists when the server registers dcode's HTTP app — the built-in dcode server, or a new-enough custom server.

Source

Thrown at libs/code/deepagents_code/client/remote_client.py:429

                        },
                    ),
                    graph=graph,
                    thread_id=thread_id,
                    operation_id=operation_id,
                )
            except NotFoundError as exc:
                # The route itself is missing. An unregistered thread cannot
                # reach here as a 404: the server catches that and answers 409
                # with its own message. A custom `graph_ref` server, or one
                # older than this operation, never registers the dcode HTTP app,
                # and the SDK's bare "404 Not Found" names neither the cause nor
                # a fix.
                msg = (
                    "This server does not provide dcode's /offload operation. "
                    "Use the built-in dcode server, or upgrade the server to a "
                    "version that registers it."
                )
                raise RuntimeError(msg) from exc
            if not isinstance(response, dict):
                msg = "Offload server returned a non-object response."
                raise TypeError(msg)
            status = response.get("status")
            if status == "complete":
                return _validated_offload_result(response.get("result"))
            request = response.get("request")
            if status != "interrupt" or not is_hook_interrupt_payload(request):
                msg = "Offload server returned an invalid operation response."
                raise RuntimeError(msg)
            invocation = request.get("request")
            invocation_id = (
                invocation.get("invocation_id")
                if isinstance(invocation, dict)
                else None
            )
            if not isinstance(invocation_id, str) or not invocation_id:
                msg = "Offload hook request has no invocation id."

View on GitHub (pinned to a1af029e6e)

Solutions

Start/use the built-in dcode server (launched by `dcode`) instead of a stock LangGraph server.
Upgrade the server to a version that registers the dcode offload route, then retry.
If you must use a custom server, port/register the dcode HTTP app so `/dcode/threads/{id}/offload` exists.
As a workaround, avoid `aoffload` and run the work client-side or via a code path that does not need server-owned offload.

Example fix

// before
agent = RemoteAgent("http://localhost:2024", graph_name="custom_graph")
result = await agent.aoffload(config=config, context=ctx, fulfill_hook=hook)

// after
# point the client at the built-in dcode server (or upgrade it) before offloading
agent = RemoteAgent(dcode_server_url)
result = await agent.aoffload(config=config, context=ctx, fulfill_hook=hook)

Defensive patterns

Strategy: try-catch

Validate before calling

# No cheap pre-check HTTP route exists; ensure the server is the dcode server before offloading.
if not server_is_builtin_dcode(url):
    raise RuntimeError("Offload requires the built-in dcode server")

Try / catch

try:
    result = await agent.aoffload(config=config, context=ctx, fulfill_hook=hook)
except RuntimeError as exc:
    if "does not provide dcode's /offload" in str(exc):
        logging.error("Server lacks /dcode offload route; start the dcode server or upgrade it")
    else:
        raise

Prevention

Only point offload-capable clients at the built-in dcode server.
Pin server and client to compatible versions and upgrade them together.
After deploying a custom server, smoke-test POST /dcode/threads/{id}/offload once.

When it happens

Trigger: Calling `RemoteAgent.aoffload` against a server that never registers the `/dcode/threads/{id}/offload` route: an older dcode server version, a plain LangGraph server, or a custom `graph_ref` server without the dcode HTTP app.

Common situations: Pointing dcode at a stock LangGraph deployment (LangSmith-hosted or self-run `langgraph dev` of a non-dcode graph); running a stale server build after upgrading the client; using a custom server graph_ref that predates the offload operation.

Related errors

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