zylon-ai/private-gpt · error · ValueError

Citations are not supported when structured output is enable

Error message

Citations are not supported when structured output is enabled.

What it means

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.

Source

Thrown at private_gpt/server/chat/chat_models.py:370

        if self.response_format.type == ResponseFormatType.json_schema:
            has_structured_output = True

        # Check that we don't have tools when structured output is enabled
        if has_structured_output:
            if self.tools:
                if self.response_format.type == ResponseFormatType.json_schema:
                    raise ValueError(
                        "Tools are not supported when response_format is set to json_schema"
                    )
                raise ValueError(
                    "Tools are not supported when structured output is enabled."
                )
            if self.mcp_servers:
                raise ValueError(
                    "MCP servers are not supported when structured output is enabled."
                )
            if system.citations.enabled:
                raise ValueError(
                    "Citations are not supported when structured output is enabled."
                )

        # Check unique tools
        if self.tools:
            tool_names = [tool.name for tool in self.tools]
            if len(tool_names) != len(set(tool_names)):
                raise ValueError(
                    "Duplicate tool names found in the tools list."
                    f" Provided tools: {self.tools}"
                    f" Unique tool names: {set(tool_names)}"
                )

        # Check tool use and result blocks
        tool_uses_ids: set[str] = set()
        tool_results_ids: set[str] = set()
        for message in self.messages:
            if isinstance(message.content, list):

View on GitHub (pinned to 4a030776a3)

Solutions

1. Disable citations for structured-output requests: set system.citations.enabled=false in that request's system config.
2. Or keep citations and drop structured output, then extract fields from the cited text yourself.
3. Make citations a per-request rather than per-deployment default.

Example fix

# before
{"system":{"citations":{"enabled":true}},"response_format":{"type":"json_schema",...}}

# after
{"system":{"citations":{"enabled":false}},"response_format":{"type":"json_schema",...}}

if structured_output_enabled(body):
    body.setdefault('system', {})['citations'] = {'enabled': False}

def citations_clean(body: dict) -> bool:
    structured = bool((body.get('output_config') or {}).get('format')) or \
        body.get('response_format', {}).get('type') == 'json_schema'
    sys_cfg = body.get('system') or {}
    citations = bool(sys_cfg.get('citations', {}).get('enabled')) if isinstance(sys_cfg, dict) else False
    return not (structured and citations)

except ValidationError as e:
    if 'Citations' in str(e):
        body['system']['citations']['enabled'] = False; retry()
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Schema must define a 'type' field
• Array schemas must define 'items'
• Array 'items' must be a dictionary representing JSON Schema
• Object schemas must define 'properties'
• Expected list or dict with 'items' key, got {type(obj)}

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/b30a67ba5d7725ac. Report an issue: GitHub.