{"record":{"id":"b30a67ba5d7725ac","repo":"zylon-ai/private-gpt","slug":"citations-are-not-supported-when-structured-output","errorCode":null,"errorMessage":"Citations are not supported when structured output is enabled.","messagePattern":"Citations are not supported when structured output is enabled\\.","errorType":"validation","errorClass":"ValueError","httpStatus":422,"severity":"error","filePath":"private_gpt/server/chat/chat_models.py","lineNumber":370,"sourceCode":"        if self.response_format.type == ResponseFormatType.json_schema:\n            has_structured_output = True\n\n        # Check that we don't have tools when structured output is enabled\n        if has_structured_output:\n            if self.tools:\n                if self.response_format.type == ResponseFormatType.json_schema:\n                    raise ValueError(\n                        \"Tools are not supported when response_format is set to json_schema\"\n                    )\n                raise ValueError(\n                    \"Tools are not supported when structured output is enabled.\"\n                )\n            if self.mcp_servers:\n                raise ValueError(\n                    \"MCP servers are not supported when structured output is enabled.\"\n                )\n            if system.citations.enabled:\n                raise ValueError(\n                    \"Citations are not supported when structured output is enabled.\"\n                )\n\n        # Check unique tools\n        if self.tools:\n            tool_names = [tool.name for tool in self.tools]\n            if len(tool_names) != len(set(tool_names)):\n                raise ValueError(\n                    \"Duplicate tool names found in the tools list.\"\n                    f\" Provided tools: {self.tools}\"\n                    f\" Unique tool names: {set(tool_names)}\"\n                )\n\n        # Check tool use and result blocks\n        tool_uses_ids: set[str] = set()\n        tool_results_ids: set[str] = set()\n        for message in self.messages:\n            if isinstance(message.content, list):","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/server/chat/chat_models.py#L352-L388","documentation":"Fourth branch of the structured-output guard: system.citations.enabled is true while structured output is enabled. Citations work by post-processing free-form model text; a json_schema/structured response cannot carry citation markup, so the combination is rejected at validation time.","triggerScenarios":"System config with citations enabled (e.g. {'citations': {'enabled': True}}) combined with output_config.format or json_schema response_format; enabling citation defaults globally then adding structured endpoints.","commonSituations":"Deployment-level citation feature flag left on; new structured-output feature added without a citations=off override; copying a system block from another request template.","solutions":["Disable citations for structured-output requests: set system.citations.enabled=false in that request's system config.","Or keep citations and drop structured output, then extract fields from the cited text yourself.","Make citations a per-request rather than per-deployment default."],"exampleFix":"# before\n{\"system\":{\"citations\":{\"enabled\":true}},\"response_format\":{\"type\":\"json_schema\",...}}\n\n# after\n{\"system\":{\"citations\":{\"enabled\":false}},\"response_format\":{\"type\":\"json_schema\",...}}","handlingStrategy":"validation","validationCode":"if structured_output_enabled(body):\n    body.setdefault('system', {})['citations'] = {'enabled': False}","typeGuard":"def citations_clean(body: dict) -> bool:\n    structured = bool((body.get('output_config') or {}).get('format')) or \\\n        body.get('response_format', {}).get('type') == 'json_schema'\n    sys_cfg = body.get('system') or {}\n    citations = bool(sys_cfg.get('citations', {}).get('enabled')) if isinstance(sys_cfg, dict) else False\n    return not (structured and citations)","tryCatchPattern":"except ValidationError as e:\n    if 'Citations' in str(e):\n        body['system']['citations']['enabled'] = False; retry()\n    else:\n        raise","preventionTips":["Default citations to disabled and enable per-request","Keep a per-endpoint system-config preset instead of sharing one globally","Test structured endpoints with the production system config"],"tags":["validation","citations","structured-output","system-config"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}