langchain-ai/deepagents · error · RuntimeError

Offload server returned an invalid operation response.

Error message

Offload server returned an invalid operation response.

What it means

When the offload response's `status` is not `"complete"`, the client requires it to be `"interrupt"` with a request payload that satisfies `is_hook_interrupt_payload` (a valid Hooks v2 hook-interrupt). Any other status, a missing `request`, or a malformed interrupt payload triggers this RuntimeError — the server spoke an offload protocol the client cannot drive.

Source

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

                # 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."
                raise RuntimeError(msg)
            logger.debug(
                "Offload round %d fulfilling hook invocation %s",
                round_index,
                invocation_id,
            )
            if round_index == _OFFLOAD_MAX_RESUME_ROUNDS:
                # The extra iteration exists to POST the last fulfillment and
                # read the result, not to answer one more hook. Without this the
                # loop fulfills 33 hooks and then reports "after 32 rounds".

View on GitHub (pinned to a1af029e6e)

Solutions

1. Align server and client versions — the hook-interrupt payload schema must match `is_hook_interrupt_payload` in `deepagents_code.hooks.interrupt`.
2. Log the raw offload response to see the actual `status`/`request` and compare against the expected schema.
3. If you run a custom server, make it return only `status: "complete"` or `status: "interrupt"` with a spec-conformant hook-interrupt request.
4. Check for middleware or serialization layers on the server that strip or rename payload fields.

from deepagents_code.hooks.interrupt import is_hook_interrupt_payload

def is_valid_offload_interrupt(response: object) -> bool:
    return (
        isinstance(response, dict)
        and response.get("status") == "interrupt"
        and is_hook_interrupt_payload(response.get("request"))
    )

try:
    result = await agent.aoffload(config=config, context=ctx, fulfill_hook=hook)
except RuntimeError as exc:
    if "invalid operation response" in str(exc):
        logging.error("Offload status/payload not understood; check server-client schema match")
    else:
        raise

When it happens

Trigger: Server returns `status` values other than `complete`/`interrupt` (e.g. `"error"`, `"pending"`, null), or `status == "interrupt"` but `request` is missing or fails `is_hook_interrupt_payload` (wrong keys/shapes in the hook interrupt).

Common situations: A server version drift where the interrupt payload schema changed; a custom/in-house offload route emitting its own status names; a hook executor version mismatch causing payload keys to be renamed server-side.

Related errors

• Offload server returned a non-object response.
• Offload hook request has no invocation id.
• Offload did not complete after {_OFFLOAD_MAX_RESUME_ROUNDS}
• Offload server returned an invalid cancellation acknowledgem
• Offload server completed without a typed result.

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