Usage Errors

Pydantic attempts to provide useful errors. The following sections provide details on common errors developers mayencounter when working with Pydantic, along with suggestions for addressing the error condition.

Class not fully defined ¶

This error is raised when a type referenced in an annotation of a pydantic-validated type(such as a subclass ofBaseModel, or a pydanticdataclass) is not defined:

fromtypingimportForwardReffrompydanticimportBaseModel,PydanticUserErrorUndefinedType=ForwardRef('UndefinedType')classFoobar(BaseModel):a:UndefinedTypetry:Foobar(a=1)exceptPydanticUserErrorasexc_info:assertexc_info.code=='class-not-fully-defined'

Or when the type has been defined after usage:

fromtypingimportOptionalfrompydanticimportBaseModel,PydanticUserErrorclassFoo(BaseModel):a:Optional['Bar']=Nonetry:# this doesn't work, see raised errorfoo=Foo(a={'b':{'a':None}})exceptPydanticUserErrorasexc_info:assertexc_info.code=='class-not-fully-defined'classBar(BaseModel):b:'Foo'# this works, thoughfoo=Foo(a={'b':{'a':None}})

For BaseModel subclasses, it can be fixed by defining the type and then calling.model_rebuild():

fromtypingimportOptionalfrompydanticimportBaseModelclassFoo(BaseModel):a:Optional['Bar']=NoneclassBar(BaseModel):b:'Foo'Foo.model_rebuild()foo=Foo(a={'b':{'a':None}})

In other cases, the error message should indicate how to rebuild the class with the appropriate type defined.

Custom JSON Schema¶

The__modify_schema__ method is no longer supported in V2. You should use the__get_pydantic_json_schema__ method instead.

The__modify_schema__ used to receive a single argument representing the JSON schema. See the example below:

Old way

frompydanticimportBaseModel,PydanticUserErrortry:classModel(BaseModel):@classmethoddef__modify_schema__(cls,field_schema):field_schema.update(examples=['example'])exceptPydanticUserErrorasexc_info:assertexc_info.code=='custom-json-schema'

The new method__get_pydantic_json_schema__ receives two arguments: the first is a dictionary denoted asCoreSchema,and the second a callablehandler that receives aCoreSchema as parameter, and returns a JSON schema. See the examplebelow:

New way

fromtypingimportAnyfrompydantic_coreimportCoreSchemafrompydanticimportBaseModel,GetJsonSchemaHandlerclassModel(BaseModel):@classmethoddef__get_pydantic_json_schema__(cls,core_schema:CoreSchema,handler:GetJsonSchemaHandler)->dict[str,Any]:json_schema=super().__get_pydantic_json_schema__(core_schema,handler)json_schema=handler.resolve_ref_schema(json_schema)json_schema.update(examples=['example'])returnjson_schemaprint(Model.model_json_schema())"""{'examples': ['example'], 'properties': {}, 'title': 'Model', 'type': 'object'}"""

Decorator on missing field¶

This error is raised when you define a decorator with a field that is not valid.

fromtypingimportAnyfrompydanticimportBaseModel,PydanticUserError,field_validatortry:classModel(BaseModel):a:str@field_validator('b')defcheck_b(cls,v:Any):returnvexceptPydanticUserErrorasexc_info:assertexc_info.code=='decorator-missing-field'

You can usecheck_fields=False if you're inheriting from the model and intended this.

fromtypingimportAnyfrompydanticimportBaseModel,create_model,field_validatorclassModel(BaseModel):@field_validator('a',check_fields=False)defcheck_a(cls,v:Any):returnvmodel=create_model('FooModel',a=(str,'cake'),__base__=Model)