{"record":{"id":"f56751abab01703e","repo":"langchain-ai/deepagents","slug":"offload-request-must-be-a-json-object","errorCode":null,"errorMessage":"Offload request must be a JSON object.","messagePattern":"Offload request must be a JSON object\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/offload_api.py","lineNumber":516,"sourceCode":"\n\ndef _operation_payload(\n    payload: object,\n) -> tuple[str, dict[str, Any], dict[str, object]]:\n    \"\"\"Validate the narrow client-to-operation request shape.\n\n    Args:\n        payload: Decoded request JSON.\n\n    Returns:\n        Operation id, runtime context, and accumulated hook responses.\n\n    Raises:\n        TypeError: If the payload or a structured field has the wrong shape.\n    \"\"\"\n    if not isinstance(payload, dict):\n        msg = \"Offload request must be a JSON object.\"\n        raise TypeError(msg)\n    operation_id = payload.get(\"operation_id\")\n    context = payload.get(\"context\")\n    responses = payload.get(\"hook_responses\", {})\n    if not isinstance(operation_id, str) or not operation_id:\n        msg = \"operation_id must be a non-empty string.\"\n        raise TypeError(msg)\n    if not isinstance(context, dict):\n        msg = \"context must be a JSON object.\"\n        raise TypeError(msg)\n    if not isinstance(responses, dict):\n        msg = \"hook_responses must be a JSON object.\"\n        raise TypeError(msg)\n    validated_context = {str(key): value for key, value in context.items()}\n    _validate_context(validated_context)\n    return (\n        operation_id,\n        _strip_transport_model_params(validated_context),\n        {str(key): value for key, value in responses.items()},","sourceCodeStart":498,"sourceCodeEnd":534,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/offload_api.py#L498-L534","documentation":"The offload API expects the request payload to be a decoded JSON object (a Python dict at the top level). Anything else — a JSON array, string, number, or undecoded raw JSON text — is rejected with this TypeError before any field is inspected. This enforces the server's wire contract that an offload request is a single object with operation_id/context/hook_responses fields.","triggerScenarios":"Calling offload() (or passing a payload into the request handling) with a JSON string like '{\"operation_id\": ...}' that was never json.loads()-ed, a list of operations, None, or a custom object instead of a dict.","commonSituations":"Double-encoded JSON from an HTTP client (body already a string), forwarding the raw request body without decoding, sending an array of requests where one object was expected, or a framework handing you a bytes body.","solutions":["Decode first: payload = json.loads(raw_body) before passing it on.","If you get bytes, use json.loads(raw) (it accepts bytes) and confirm the result is a dict.","If you intended to send multiple operations, send them one at a time or wrap them under an object key the API defines.","Log/inspect type(payload) to confirm you are not passing a str wrapper around an already-parsed dict."],"exampleFix":"// before\nresult = await offload('{\"operation_id\": \"op1\", \"context\": {}}')\n// after\nimport json\nresult = await offload(json.loads('{\"operation_id\": \"op1\", \"context\": {}}'))","handlingStrategy":"type-guard","validationCode":"import json\n\ndef ensure_object_payload(raw):\n    payload = json.loads(raw) if isinstance(raw, (str, bytes, bytearray)) else raw\n    if not isinstance(payload, dict):\n        raise ValueError(\"Offload payload must decode to a JSON object\")\n    return payload","typeGuard":"def is_json_object(value) -> bool:\n    return isinstance(value, dict)","tryCatchPattern":"try:\n    state = await offload(thread_id, payload)\nexcept TypeError as exc:\n    if \"must be a JSON object\" in str(exc):\n        state = await offload(thread_id, json.loads(payload))\n    else:\n        raise","preventionTips":["Always json.loads() HTTP bodies/bytes before passing them as payloads","Never pre-serialize nested fields with json.dumps inside an already-decoded payload","Assert isinstance(payload, dict) at the boundary of your transport layer","Send one operation object per request, not an array"],"tags":["type-error","json","validation","payload"],"backgroundTag":"invalid-json-payload","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}