ValidationError raised on validation failures
Pydantic raises a ValidationError whenever it finds an error in the data it is validating. This exception contains information about all the errors and how they happened.
errors/validation-errors
14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Validators should raise ValueError or AssertionError, not ValidationError
Validation code should not raise ValidationError itself, but rather raise a ValueError or AssertionError (or subclass thereof). These exceptions will be caught and used to populate the final ValidationError.
ValidationError methods to access errors
ValidationError provides several methods to access error information: errors() returns a list of ErrorDetails objects found in the input data; error_count() returns the number of errors; json() returns a JSON representation of the list of errors; str(e) returns a human-readable representation of the errors.
ErrorDetails object structure and properties
ErrorDetails is a dictionary containing: ctx (optional object with values required to render the error message), input (the input provided for validation), loc (the error's location as a list), msg (human-readable explanation of the error), type (computer-readable identifier of the error type), url (documentation URL giving information about the error).
Error location in nested models
The first item in the loc list is the field where the error occurred. If the field is a sub-model, subsequent items in the loc list indicate the nested location of the error.
Validation error example with multiple errors
Example code demonstrating ValidationError handling: from pydantic import BaseModel, Field, ValidationError, field_validator class Location(BaseModel): lat: float = 0.1 lng: float = 10.1 class Model(BaseModel): is_required: float gt_int: int = Field(gt=42) list_of_ints: list[int] a_float: float recursive_model: Location @field_validator('a_float', mode='after') @classmethod def validate_float(cls, value: float) -> float: if value > 2.0: raise ValueError('Invalid float value') return value data = { 'list_of_ints': ['1', 2, 'bad'], 'a_float': 3.0, 'recursive_model': {'lat': 4.2, 'lng': 'New York'}, 'gt_int': 21, } try: Model(**data) except ValidationError as e: print(e.errors())
Error context values for message formatting
The ctx field in an ErrorDetails object contains values required to render the error message. These values can be used in custom error messages via string formatting (e.g., {expected_schemes}, {gt}, {error}).
ValidationError contains error location (loc)
When a ValidationError occurs during validation of multiple records, the error's loc field gives the index of the failing record, which is useful for locating the offending record in large datasets.
ValidationError indicates API response format changes
When validating HTTP responses with Pydantic, a ValidationError is often the first sign that an API has changed its response format. Recording failed validations with Logfire captures both the error and the data that triggered it, helping identify what the response actually contained and when the problem started.
Error handling in queue consumers with Logfire
When using model_validate_json() in message consumers, if a ValidationError is raised, the message may have already been removed from the queue, making the failure hard to reproduce. Recommend recording failed validations using Logfire with logfire.instrument_pydantic(record='failure') to capture the message body alongside the error.
ValidationError structure with error details
When validation fails, Pydantic raises a ValidationError containing a list of error dictionaries. Each error dictionary includes 'type' (error code), 'loc' (field location tuple), 'msg' (error message), 'input' (the input data), and 'url' (link to error documentation).
Pydantic example: ValidationError handling
Example code showing validation error handling: ```python from datetime import datetime from pydantic import BaseModel, PositiveInt, ValidationError class User(BaseModel): id: int name: str = 'John Doe' signup_ts: datetime | None tastes: dict[str, PositiveInt] external_data = {'id': 'not an int', 'tastes': {}} try: User(**external_data) except ValidationError as e: print(e.errors()) ``` This example shows how to catch and handle ValidationError exceptions.
V2 non-breaking changes allowed in minor releases
The following changes will NOT be considered breaking in Pydantic V2 minor releases: bug fixes relying on undocumented features, changing JSON Schema reference formats, changing msg/ctx/loc fields of ValidationError exceptions (but not type field), adding new keys to ValidationError exceptions, adding new ValidationError errors, changing __repr__ behavior, and changing core schema contents.
ValidationError fields - programmatic parsing
When programmatically parsing ValidationError exceptions, use the type field rather than msg, ctx, or loc fields, as these fields may change in minor releases while type will not.