{"id":"49c6550fd35b462e","repo":"pydantic/pydantic","slug":"invalid-validation-alias-type-it-should-be-str","errorCode":null,"errorMessage":"Invalid `validation_alias` type. it should be `str`, `AliasChoices`, or `AliasPath`","messagePattern":"Invalid `validation_alias` type\\. it should be `str`, `AliasChoices`, or `AliasPath`","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"pydantic/fields.py","lineNumber":1347,"sourceCode":"        raise PydanticUserError('`regex` is removed. use `pattern` instead', code='removed-kwargs')\n\n    if extra:\n        warn(\n            'Using extra keyword arguments on `Field` is deprecated and will be removed.'\n            ' Use `json_schema_extra` instead.'\n            f' (Extra keys: {\", \".join(k.__repr__() for k in extra.keys())})',\n            PydanticDeprecatedSince20,\n            stacklevel=2,\n        )\n        if not json_schema_extra or json_schema_extra is _Unset:\n            json_schema_extra = extra  # type: ignore\n\n    if (\n        validation_alias\n        and validation_alias is not _Unset\n        and not isinstance(validation_alias, (str, AliasChoices, AliasPath))\n    ):\n        raise TypeError('Invalid `validation_alias` type. it should be `str`, `AliasChoices`, or `AliasPath`')\n\n    if serialization_alias in (_Unset, None) and isinstance(alias, str):\n        serialization_alias = alias\n\n    if validation_alias in (_Unset, None):\n        validation_alias = alias\n\n    include = extra.pop('include', None)  # type: ignore\n    if include is not None:\n        warn(\n            '`include` is deprecated and does nothing. It will be removed, use `exclude` instead',\n            PydanticDeprecatedSince20,\n            stacklevel=2,\n        )\n\n    return FieldInfo.from_field(\n        default,\n        default_factory=default_factory,","sourceCodeStart":1329,"sourceCodeEnd":1365,"githubUrl":"https://github.com/pydantic/pydantic/blob/2e5f0e2b4218de31709f1cf9c5bc61ea97a68835/pydantic/fields.py#L1329-L1365","documentation":"Raised by Field() at fields.py:1347 when validation_alias is supplied but is not an instance of str, AliasChoices, or AliasPath. Pydantic restricts validation aliases to these three types so the alias resolution algorithm can deterministically traverse the input payload.","triggerScenarios":"Calling Field(validation_alias=['a', 'b']) (a bare list instead of AliasPath); Field(validation_alias=re.compile('...')); passing a tuple or dict as validation_alias; helper code that forwards arbitrary objects.","commonSituations":"Migrating from v1's regex aliases; building aliases programmatically and forgetting to wrap paths in AliasPath; confusing AliasChoices (multiple keys, any matches) with AliasPath (nested path) semantics.","solutions":["Use a plain str for a single-key alias: Field(validation_alias='alt_name').","Wrap a nested path with AliasPath: Field(validation_alias=AliasPath('user', 'email')).","Wrap multiple alternative keys with AliasChoices: Field(validation_alias=AliasChoices('email', 'e-mail'))."],"exampleFix":"// before\nx: int = Field(validation_alias=['user', 'id'])\n// after\nfrom pydantic import AliasPath\nx: int = Field(validation_alias=AliasPath('user', 'id'))","handlingStrategy":"type-guard","validationCode":"from pydantic import AliasChoices, AliasPath\n\ndef coerce_validation_alias(v):\n    if isinstance(v, (str, AliasChoices, AliasPath)):\n        return v\n    if isinstance(v, list):\n        return AliasPath(*v)\n    if isinstance(v, tuple):\n        return AliasPath(*v)\n    raise TypeError('Invalid validation_alias type')","typeGuard":"def is_valid_validation_alias(v) -> bool:\n    from pydantic import AliasChoices, AliasPath\n    return isinstance(v, (str, AliasChoices, AliasPath))","tryCatchPattern":"try:\n    Field(validation_alias=v)\nexcept TypeError as e:\n    if 'validation_alias' in str(e):\n        from pydantic import AliasPath\n        return Field(validation_alias=AliasPath(*v))\n    raise","preventionTips":["Wrap multi-key paths in AliasPath.","Use AliasChoices for alternative single-level keys.","Validate alias type in custom Field wrappers."],"tags":["pydantic","field","alias","validation-alias"],"analyzedSha":"2e5f0e2b4218de31709f1cf9c5bc61ea97a68835","analyzedAt":"2026-08-04T19:54:21.281Z","schemaVersion":2}