zylon-ai/private-gpt · error · ValueError

JSON schema must be provided when response format is json_sc

Error message

JSON schema must be provided when response format is json_schema

What it means

Raised in chat_request_mapper while deriving the structured-output model: request.response_format.type is ResponseFormatType.json_schema but request.response_format.json_schema is None/empty. When you declare a json_schema response format you must supply the actual JSON schema payload, otherwise there is nothing from which to build the output model via create_model_from_json_schema.

Source

Thrown at private_gpt/server/chat/chat_request_mapper.py:111

        return output_tools

    async def _configure_output_cls_from_json_schema(
        self,
        request: ChatBody,
    ) -> type[BaseModel] | None:
        """Define the output schema based on the response format."""
        if (
            request.output_config
            and request.output_config.format
            and request.output_config.format.json_schema
        ):
            return create_model_from_json_schema(
                request.output_config.format.json_schema
            )

        if request.response_format.type == ResponseFormatType.json_schema:
            if not request.response_format.json_schema:
                raise ValueError(
                    "JSON schema must be provided when response format is json_schema"
                )
            return create_model_from_json_schema(request.response_format.json_schema)

        # Default to None for text responses
        return None

    async def _collect_sampling_params(
        self,
        request: ChatBody,
    ) -> dict[str, Any]:
        """Collect sampling parameters from the request request."""
        sampling_params: dict[str, Any] = {}
        if request.seed is not None:
            sampling_params["seed"] = request.seed
        if request.min_p is not None:
            sampling_params["min_p"] = request.min_p
        if request.top_p is not None:

View on GitHub (pinned to 4a030776a3)

Solutions

1. Provide the schema inline: response_format = {"type": "json_schema", "json_schema": {"schema": {...}}} (match the API's expected shape)
2. Or use the newer output_config.format.json_schema field, which is checked first
3. Verify with the server's OpenAPI spec which field name/shape the installed version expects after upgrades

Example fix

# before
{"response_format": {"type": "json_schema"}}

# after
{"response_format": {"type": "json_schema", "json_schema": {"name": "answer", "schema": {"type": "object", "properties": {"answer": {"type": "string"}}, "required": ["answer"]}}}}

rf = body.get("response_format") or {}
if rf.get("type") == "json_schema" and not (rf.get("json_schema") or (body.get("output_config") or {}).get("format", {}).get("json_schema")):
    raise ValueError("response_format.type=json_schema requires response_format.json_schema")

def is_valid_response_format(body: dict) -> bool:
    rf = body.get("response_format") or {}
    if rf.get("type") == "json_schema":
        return bool(rf.get("json_schema")) or bool((body.get("output_config") or {}).get("format", {}).get("json_schema"))
    return True

try:
    await client.chat(body)
except ValueError as e:
    if "JSON schema must be provided" in str(e):
        body["response_format"]["json_schema"] = {"name": "out", "schema": MY_SCHEMA}
        await client.chat(body)
    else:
        raise

When it happens

Trigger: POST /v1/chat/completions (or the chat endpoint) with body {"response_format": {"type": "json_schema"}} and no json_schema field, while also not setting output_config.format.json_schema (the alternative field that takes precedence).

Common situations: OpenAI-style clients sending only {"type": "json_schema"} without a schema; version drift where the schema moved into output_config; typos like "jsonSchema" casing so the field is silently dropped.

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/41e709238e9fdc64. Report an issue: GitHub.