Pydantic V2 Validation Errors in LLM JSON Output: What Each Means, Tested

What I ran

All the Pydantic checks ran offline on Python 3.10.0 with Pydantic 2.12.5 (the table below shows the error types it reported). The provider checks used the Gemini API on 9 October 2026 with gemini-3.1-flash-lite and a free-tier key. I did not test any OpenAI model: the earlier version of this guide was about one, and I have no key for it, so everything here is about Pydantic itself and about Gemini.

The errors, their causes, and the fix

Type coercion: "42" is fine, "10.7" and "ten" are not

By default (lax mode) Pydantic V2 converts compatible values. For user_id: int the string "42" became 42 and "10.0" became 10, from Python and from JSON. The number 10.7 failed with int_from_float and the string "ten" with int_parsing. Only with ConfigDict(strict=True) did "42" fail (int_type), while the JSON number 42 still passed. So the advice that V2 rejects numeric strings is true only when you turn strict mode on; the default is the forgiving behavior that LLM output usually needs.

Optional is not optional without a default

In Pydantic V2, summary: Optional[str] means "a string or None is allowed", not "the key may be absent". Calling the model without the key raised missing ("Field required"), for Optional[str] and for str | None alike. Adding = None fixed it: both OptDefault() and OptDefault.model_validate_json("{}") returned summary=None. If your schema comes from a model with Optional fields and the LLM sometimes leaves a key out, this is the first thing to check.

class Analysis(BaseModel):
    summary: str | None = None       # key may be absent or null
    confidence: float = 0.0          # key may be absent, defaults to 0.0

Truncated and wrapped replies are JSON errors, not schema errors

Pydantic reported json_invalid for every broken-JSON case I tried: a reply cut after 64, 30 or 5 characters ("EOF while parsing a string"), a reply wrapped in a Markdown fence ("expected value at line 1 column 1") and a trailing comma. In a live test I asked gemini-3.1-flash-lite for twelve items with an output limit of 60 tokens. The API answered HTTP 200 with finishReason: MAX_TOKENS, and the text ended mid-object:

...the apple is a crisp and refreshing snack."
    },
    {
      "name":

Pydantic's verdict was json_invalid ("EOF while parsing a value"). Note that the HTTP status was 200: the failure shows up only in the finish reason. A small wrapper makes that check hard to forget. I tested it on five inputs (clean, fenced, cut off, wrong type, missing field) and it behaved as the comments say:

def parse_reply(model_cls, text, finish_reason):
    """Validate an LLM JSON reply; refuse replies that were cut off, strip a Markdown fence."""
    if finish_reason not in (None, "STOP"):
        raise RuntimeError(f"reply not complete (finish reason: {finish_reason})")
    cleaned = text.strip()
    if cleaned.startswith("```"):
        cleaned = cleaned.split("\n", 1)[1].rsplit("```", 1)[0]
    return model_cls.model_validate_json(cleaned)

Sending a Pydantic schema to a provider

A Pydantic model with a nested model, an Optional field and extra="forbid" produces this kind of schema from model_json_schema(): a $defs section with a $ref, "additionalProperties": false, and anyOf with {"type": "null"}. I sent that exact schema to Gemini in two fields:

• responseSchema: HTTP 400, Unknown name "$defs" ... Cannot find field.
• responseJsonSchema: HTTP 200, and Pydantic validated the reply (Wrapper(owner=Profile(username='bob_smith', age=41), tags=['red', 'blue'])).

So if a provider rejects your schema, the problem is often which field you pass it in, not your Pydantic model. The keyword-by-keyword results are in my test of Gemini's schema fields. A schema accepted by the provider also does not guarantee that your validators pass: @field_validator runs only in your code, after the reply arrives.

Keeping validation errors useful

1. Log the raw reply with the error. ValidationError.errors() gives the type, the field path and a message; keep the text next to it so you can reproduce the failure.
2. Separate retryable from non-retryable errors. json_invalid from a cut-off reply needs a larger output limit or a smaller request; value_error may be worth one retry with the message appended to the prompt.
3. Keep the LLM-facing model small. A separate, flat model for the reply is easier to reason about than reusing a database model. I did not test whether this changes accuracy.

What I did not test

Any OpenAI model or its parse helper, strict structured-output modes of other providers, Pydantic 2.13 or later (the Python 3.10.0 here breaks the newest releases), and large or deeply nested schemas. Rerun the small checks above on your own Pydantic and Python versions before relying on exact error messages.

Sources and Further Reading

• Validation errors — Pydantic docs (the error types listed above)
• Conversion table — Pydantic docs (what lax and strict mode accept)
• Structured outputs — Google AI for Developers