BerriAI/litellm · error · JSONSchemaValidationError

litellm.JSONSchemaValidationError: model=

Error message

litellm.JSONSchemaValidationError: model={model}, returned an invalid response={raw_response}, for schema={schema}.\nAccess raw response with `e.raw_response`

What it means

Raised by validate_schema() (called from litellm.utils during response post-processing) when response-format enforcement is enabled and the completion text cannot even be parsed as JSON: json.loads() raises JSONDecodeError and LiteLLM converts it into JSONSchemaValidationError with model/llm_provider empty but raw_response and schema attached. Enforcement is on when litellm.enable_json_schema_validation is True (or per-request enable_json_schema_validation) with a response_format json_schema/Pydantic model, or response_format has enforce_validation: True. Access the offending text via e.raw_response.

Solutions

Make the supplied/mocked response a JSON string: json.dumps({...}).
For Pydantic response_format, build the mock from the model: json.dumps(MyModel(...).model_dump()).
Catch litellm.JSONSchemaValidationError and inspect e.raw_response / e.schema to see exactly what failed.
Disable enforcement where validation is not wanted (drop enforce_validation or enable_json_schema_validation for that call/test).

Example fix

# before
litellm.completion(model='gpt-4o', messages=m, response_format=MyModel, mock_response='sure thing!')

# after
import json
litellm.completion(model='gpt-4o', messages=m, response_format=MyModel, mock_response=json.dumps(MyModel(name='x', age=1).model_dump()))

Defensive patterns

Strategy: try-catch

Validate before calling

import json

if isinstance(mock_response, str):
    try:
        json.loads(mock_response)
    except json.JSONDecodeError:
        mock_response = json.dumps({'field': mock_response})  # or build from the Pydantic model
resp = litellm.completion(model='gpt-4o', messages=m, response_format=MyModel, mock_response=mock_response)

Try / catch

import litellm

try:
    resp = litellm.completion(model='gpt-4o', messages=m, response_format=MyModel, mock_response=mock_response)
except litellm.JSONSchemaValidationError as e:
    raw = e.raw_response  # inspect the offending text
    fixed = json.dumps(MyModel(name='x', age=1).model_dump())
    resp = litellm.completion(model='gpt-4o', messages=m, response_format=MyModel, mock_response=fixed)

Prevention

Generate structured-output mocks from the Pydantic model itself so they always parse.
Keep mocks and response_format models in the same module so renames stay in sync.
Run a tiny json.loads() assert over mock fixtures in CI.

When it happens

Trigger: litellm.completion(..., mock_response='some non-json text', response_format=<Pydantic model or {'type':'json_schema','json_schema':...}>) with validation enabled — the classic unit-test case; or any path feeding a non-JSON string into a validated response_format. The two call sites are in the mock-response post-processing in litellm/utils.py.

Common situations: Tests using mock_response strings ('hello', prose answers) while response_format expects structured output; mocks written before response_format was added; enabling enable_json_schema_validation globally and forgetting mocks must now be valid JSON.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/ed93c845861ff977. Report an issue: GitHub.

Appendix: source

Thrown at litellm/litellm_core_utils/json_validation_rule.py:114

    return normalized_tool


def validate_schema(schema: dict, response: str):
    """
    Validate if the returned json response follows the schema.

    Params:
    - schema - dict: JSON schema
    - response - str: Received json response as string.
    """
    from jsonschema import ValidationError, validate

    from litellm import JSONSchemaValidationError

    try:
        response_dict: Final = json.loads(response)
    except json.JSONDecodeError:
        raise JSONSchemaValidationError(model="", llm_provider="", raw_response=response, schema=json.dumps(schema))

    try:
        validate(response_dict, schema=schema)
    except ValidationError:
        raise JSONSchemaValidationError(model="", llm_provider="", raw_response=response, schema=json.dumps(schema))

View on GitHub (pinned to 77b7c6c40c)