errors/error-codes

152 notes in this subject, read out of this brain and free to use. This is page 1 of 3.

Common validation error types

Common Pydantic validation error types include: missing (required field is missing), greater_than (value not greater than specified threshold), int_parsing (string cannot be parsed as integer), value_error (custom validation error from field_validator), float_parsing (string cannot be parsed as number).

type-adapter-config-unused error code

The error code 'type-adapter-config-unused' is raised when config is passed to TypeAdapter for a type that has its own config that cannot be overridden (BaseModel, TypedDict, or dataclass). Instead, subclass the type and set __pydantic_config__ on it.

circular-reference-schema error code

The error code 'circular-reference-schema' is raised when a circular reference is found in a schema that would otherwise result in infinite recursion, such as type A = A or mutually recursive types.

validate-call-type error code

The error code 'validate-call-type' is raised when validate_call is used with unsupported callables. Supported callables are functions (including lambdas but not built-ins), methods, and functools.partial instances. For @classmethod, @staticmethod, and @property, these decorators must come before @validate_call. Classes cannot be decorated; apply @validate_call to __init__ or __new__ instead.

clashing-init-and-init-var error code

The error code is raised when a dataclass field has both init=False and init_var=True, which are mutually exclusive settings.

root-model-extra error code

The error code 'root-model-extra' is raised when model_config['extra'] is set to any value on a RootModel subclass. RootModel cannot store or accept extra fields during initialization.

class-not-fully-defined error code

The error code 'class-not-fully-defined' is raised when a type referenced in an annotation of a pydantic-validated type (such as a BaseModel subclass or pydantic dataclass) is not defined, or when a type is used before it has been defined. This can be fixed for BaseModel subclasses by defining the type and then calling .model_rebuild().

overlapping-unpack-typed-dict error code

The error code 'overlapping-unpack-typed-dict' is raised when a TypedDict used to type hint variadic keyword parameters has field names that overlap with other function parameters, unless those parameters are positional-only.

validate-by-alias-and-name-false error code

The error code 'validate-by-alias-and-name-false' is raised when both validate_by_alias and validate_by_name are set to False in model configuration. This is not allowed because it would make it impossible to populate attributes.

unpack-typed-dict error code

The error code 'unpack-typed-dict' is raised when Unpack is used with something other than a TypedDict class object to type hint variadic keyword parameters.

with-config-on-model error code

The error code 'with-config-on-model' is raised when the with_config decorator is used on a BaseModel subclass. Use model_config attribute instead.

model-config-invalid-field-name error code

The error code 'model-config-invalid-field-name' is raised when model_config is used as the name of a field in a BaseModel.

dataclass-init-false-extra-allow error code

The error code is raised when extra='allow' is set on a dataclass that has any fields with init=False. This combination is not allowed.

unevaluable-type-annotation error code

The error code 'unevaluable-type-annotation' is raised when a type annotation name clashes with a field name, such as defining a field named 'date' with type annotation 'date'. Workaround by using qualified imports like datetime.date or aliasing the import.

invalid-self-type error code

The error code 'invalid-self-type' is raised when Self is used outside of class field annotations. Self can only be used to annotate fields in BaseModel, NamedTuple, TypedDict, or dataclass subclasses.

custom-json-schema error code and __get_pydantic_json_schema__

The error code 'custom-json-schema' is raised when __modify_schema__ method is used. In Pydantic V2, use __get_pydantic_json_schema__ instead. This method receives two arguments: a CoreSchema dictionary and a GetJsonSchemaHandler callable. Call handler.resolve_ref_schema(json_schema) to resolve references before modifying the schema.

decorator-invalid-fields error code

The error code 'decorator-invalid-fields' is raised when field names provided to @field_validator or @field_serializer decorators are not strings or are provided as a list. Fields must be provided as separate string arguments, for example @field_validator('a', 'b').

decorator-missing-arguments error code

The error code 'decorator-missing-arguments' is raised when @field_validator or @field_serializer decorators are used bare without any arguments. At least one field name must be provided as an argument.

decorator-missing-field error code

The error code 'decorator-missing-field' is raised when a decorator is defined with a field that does not exist in the model. This can be worked around by using check_fields=False if inheriting from the model and the field is intended to be validated in a subclass.

discriminator-no-field error code

The error code 'discriminator-no-field' is raised when a model in a discriminated union does not define the discriminator field specified in Field(discriminator='field_name').

discriminator-alias-type error code

The error code 'discriminator-alias-type' is raised when a non-string alias (such as AliasChoices) is defined on a discriminator field.

discriminator-needs-literal error code

The error code 'discriminator-needs-literal' is raised when a discriminator field does not have a Literal type annotation.

discriminator-alias error code

The error code 'discriminator-alias' is raised when different models in a discriminated union define different validation_alias values on the discriminator field.

discriminator-validator error code

The error code 'discriminator-validator' is raised when a before, wrap, or plain mode validator is used on a discriminator field. This is disallowed because the discriminator field is used to determine which model type to use for validation, so validators that might change its value cannot be applied. Use a standard union without discriminator as a workaround.

callable-discriminator-no-tag error code

The error code 'callable-discriminator-no-tag' is raised when a union using a callable Discriminator does not have Tag annotations for all union cases.

typed-dict-version error code

The error code 'typed-dict-version' is raised when typing.TypedDict is used instead of typing_extensions.TypedDict on Python versions prior to 3.12.

model-field-overridden error code

The error code 'model-field-overridden' is raised when a field defined on a base class is overridden by a non-annotated attribute in a subclass.

model-field-missing-annotation error code

The error code 'model-field-missing-annotation' is raised when a field does not have a type annotation. This can be resolved by: annotating the field as ClassVar if it should not be a field, or updating model_config['ignored_types'].

config-both error code

The error code 'config-both' is raised when both class Config and model_config are defined together in a BaseModel subclass. Only one should be used; model_config is the Pydantic V2 approach.

removed-kwargs error code

The error code 'removed-kwargs' is raised when keyword arguments that are not available in Pydantic V2 are used, such as regex in Field().

dataclass-on-model error code

The error code 'dataclass-on-model' is raised when the Pydantic dataclass decorator is used on a class that is already a BaseModel subclass.

invalid-for-json-schema error code

The error code 'invalid-for-json-schema' is raised when Pydantic fails to generate a JSON schema for some CoreSchema, such as with ImportString type.

json-schema-already-used error code

The error code 'json-schema-already-used' is raised when the JSON schema generator has already been used to generate a JSON schema. A new instance must be created to generate another JSON schema.

base-model-instantiated error code

The error code 'base-model-instantiated' is raised when you instantiate BaseModel directly. Pydantic models should inherit from BaseModel rather than instantiate it.

undefined-annotation error code

The error code 'undefined-annotation' is raised by PydanticUndefinedAnnotation when handling undefined annotations during CoreSchema generation, such as when a forward reference cannot be resolved.

schema-for-unknown-type error code

The error code 'schema-for-unknown-type' is raised when Pydantic fails to generate a CoreSchema for some type, such as when a non-type value is used as a type annotation.

import-error error code

The error code 'import-error' is raised when you try to import an object that was available in Pydantic V1 but has been removed in Pydantic V2. See the Migration Guide for more information.

create-model-field-definitions error code

The error code 'create-model-field-definitions' is raised when invalid field definitions are provided to create_model().

validator-instance-method error code

The error code 'validator-instance-method' is raised when a validator is applied to an instance method instead of a classmethod. Field validators should be defined as classmethods.

validator-input-type error code

The error code 'validator-input-type' is raised when json_schema_input_type is explicitly specified with a mode that is not 'before', 'plain', or 'wrap'. The json_schema_input_type argument is only available for validators where the value can be anything, not for 'after' validators.

root-validator-pre-skip error code

When using @root_validator with pre=False (the default), skip_on_failure=True must be specified. The skip_on_failure=False option is no longer available in Pydantic V2.

model-serializer-instance-method error code

The error code 'model-serializer-instance-method' is raised when @model_serializer is applied to a classmethod or a method without self, or when applied to any method without proper instance method signature.

validator-field-config-info parameters in V2

In Pydantic V2, the field and config parameters are not available for validators. Use the info parameter instead. Configuration can be accessed via info.config as a dictionary.

validator-v1-signature error code

The error code 'validator-v1-signature' is raised when an unsupported signature is used for a Pydantic V1-style validator, such as including unexpected parameters like foo.

validator-signature error code

The error code 'validator-signature' is raised when a field_validator or model_validator function has the wrong signature, such as missing the value parameter.

field-serializer-signature error code

The error code 'field-serializer-signature' is raised when a field_serializer function has an incorrect signature. Valid signatures require at least self and value parameters, and optionally info for plain mode or nxt/handler for wrap mode.

model-serializer-signature error code

The error code 'model-serializer-signature' is raised when a model_serializer function has an incorrect signature. Valid signatures require self and info for plain mode, or self, handler, and info for wrap mode. The info parameter can be omitted.

multiple-field-serializers error code

The error code 'multiple-field-serializers' is raised when multiple field_serializer decorators are defined for the same field.

invalid-annotated-type error code

The error code 'invalid-annotated-type' is raised when an annotation cannot properly annotate a type, such as using FutureDate() annotation with str type.

date_from_datetime_inexact error when datetime has nonzero time component for date field

The date_from_datetime_inexact error is raised when the input datetime value provided for a date field has a nonzero time component. For a timestamp to parse into a date field, the time components must all be zero.

dataclass_type error when input is invalid for dataclass field

The dataclass_type error is raised when the input value is not valid for a dataclass field.

bytes_too_long error when bytes length exceeds max_length

The bytes_too_long error is raised when the length of a bytes value is greater than the field's max_length constraint.

dataclass_exact_type error when dataclass validation fails with strict=True

The dataclass_exact_type error is raised when validating a dataclass with strict=True and the input is not an instance of the dataclass.

complex_type error when input cannot be interpreted as complex number

The complex_type error is raised when the input value cannot be interpreted as a complex number, such as passing False.

bytes_invalid_encoding error when bytes value is invalid under configured encoding

The bytes_invalid_encoding error is raised when a bytes value is invalid under the configured encoding, for example 'a' is invalid hex because it has an odd number of digits.

assertion_error raised when assert statement fails during validation

The assertion_error is raised when a failing assert statement is encountered during validation, such as in a field_validator.

complex_str_parsing error when string cannot be parsed as complex number

The complex_str_parsing error is raised when the input value is a string that cannot be parsed as a complex number because it does not follow Python's complex number string format rules.

callable_type error when input is not a valid callable

The callable_type error is raised when the input value is not valid as a callable, such as when using ImportString[Callable] with an invalid import path.

bool_type error when input type is invalid for bool field

The bool_type error is raised when the input value's type is not valid for a bool field, such as None. This error is also raised for strict fields when the input value is not an instance of bool.

bytes_type error when input type is invalid for bytes field

The bytes_type error is raised when the input value's type is not valid for a bytes field, such as 123. This error is also raised for strict fields when the input value is not an instance of bytes.

Give your agent this brain