{"record":{"id":"691d1fb2e3aa9cf8","repo":"zylon-ai/private-gpt","slug":"request-too-large-error","errorCode":"REQUEST_TOO_LARGE_ERROR","errorMessage":"structured_outputs JSON must decode to an object; got {type(structured_outputs).__name__}","messagePattern":"structured_outputs JSON must decode to an object; got (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":413,"severity":"error","filePath":"private_gpt/components/llm/custom/base.py","lineNumber":127,"sourceCode":"    API serializers use ``json`` instead of the model's internal\n    ``json_schema`` field. Normalize those representations before backend\n    specific code accesses the typed fields.\n    \"\"\"\n    if structured_outputs is None:\n        return None\n    if isinstance(structured_outputs, StructuredOutputsParams):\n        return structured_outputs\n\n    if isinstance(structured_outputs, str):\n        try:\n            structured_outputs = json.loads(structured_outputs)\n        except json.JSONDecodeError as exc:\n            raise ValueError(\n                \"structured_outputs must be a StructuredOutputsParams, \"\n                \"mapping, JSON object string, or None\"\n            ) from exc\n        if not isinstance(structured_outputs, Mapping):\n            raise TypeError(\n                \"structured_outputs JSON must decode to an object; \"\n                f\"got {type(structured_outputs).__name__}\"\n            )\n\n    if isinstance(structured_outputs, Mapping):\n        values = dict(structured_outputs)\n        if \"json\" in values and \"json_schema\" not in values:\n            values[\"json_schema\"] = values.pop(\"json\")\n        return StructuredOutputsParams.model_validate(values)\n\n    raise TypeError(\n        \"structured_outputs must be a StructuredOutputsParams, mapping, \"\n        \"JSON object string, or None; \"\n        f\"got {type(structured_outputs).__name__}\"\n    )\n\n\nclass SamplingParameters(BaseModel):","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/llm/custom/base.py#L109-L145","documentation":"TypeError raised when the structured_outputs string parsed as valid JSON but decoded to a non-object top-level value (list, string, number, bool, null). The normalizer requires a JSON object because it must map keys like json/json_schema into StructuredOutputsParams fields; arrays or scalars are meaningless there.","triggerScenarios":"Passing structured_outputs='[{\"json_schema\": ...}]' (array-wrapped schema) or '\"{\"\"json_schema\"\": ...}\"' (still a string after decode) — anything whose decoded root is not a Mapping.","commonSituations":"Schemas authored as JSON arrays of definitions; double-encoded JSON strings that decode to a str; copying schema fragments from OpenAPI files that root in lists.","solutions":["Wrap the schema in an object: use {\"json_schema\": {...}} not a bare array.","If the string decodes to another string, decode again or stop pre-encoding the payload.","Read the type name in the message (got list / got str) to see exactly what the decode produced.","Pass a StructuredOutputsParams or plain dict to bypass string handling entirely."],"exampleFix":"# before\nparams = '[{\"name\": \"answer\", \"type\": \"object\"}]'\n\n# after\nparams = {\"json_schema\": {\"name\": \"answer\", \"type\": \"object\", \"schema\": {...}}}","handlingStrategy":"type-guard","validationCode":"import json\nobj = json.loads(structured_outputs) if isinstance(structured_outputs, str) else structured_outputs\nif not isinstance(obj, dict):\n    raise TypeError(f'structured_outputs root must be an object, got {type(obj).__name__}')","typeGuard":"from collections.abc import Mapping\n\ndef is_structured_outputs_mapping(value: object) -> bool:\n    if isinstance(value, str):\n        try:\n            value = json.loads(value)\n        except json.JSONDecodeError:\n            return False\n    return isinstance(value, Mapping)","tryCatchPattern":"try:\n    llm.stream_chat(messages, structured_outputs=payload)\nexcept TypeError as e:\n    if 'must decode to an object' in str(e):\n        payload = {'json_schema': payload[0]}  # unwrap array-wrapped schema","preventionTips":["Always wrap schemas in {\"json_schema\": ...} objects, never bare arrays.","Watch out for double-encoded JSON — decode until the root is a dict."],"tags":["llm","structured-output","json","type-error"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}