Emit warning when field-specific metadata is used in invalid contexts by Viicos · Pull Request #12028 · pydantic/pydantic

Viicos · 2025-06-30T17:35:59Z

Best reviewed commit per commit.

In a nutshell, this now raises a warning:

from typing import Annotated

from pydantic import BaseModel, Field

type MyInt = Annotated[int, Field(alias='my_alias')]

class Model(BaseModel):
    # see the warning in https://docs.pydantic.dev/latest/concepts/types/#named-type-aliases for more info:
    a: MyInt
"""
>>> UnsupportedFieldAttributeWarning: The 'alias' attribute with value 'my_alias' was provided to the `Field()` function, which 
>>> is unsupported in the context it was used. 'alias' is field-specific metadata, and can only be attached to a model field 
>>> using `Annotated` metadata or by assignment (note that using `Annotated` type aliases using the `type` statement 
>>> isn't supported).
"""

# Other use case:
class Model(BaseModel):
    a: list[Annotated[int, Field(default=1)]]
"""
>>> UnsupportedFieldAttributeWarning: The 'default' attribute with value 1 was provided to the `Field()` function, which 
>>> is unsupported in the context it was used. 'alias' is field-specific metadata, and can only be attached to a model field 
>>> using `Annotated` metadata or by assignment (note that using `Annotated` type aliases using the `type` statement 
>>> isn't supported).
"""

We still need to figure out if we want the warning to be raised for default and default_factory. Currently, the following works:

type MyInt = Annotated[int, Field(default=1)]

class Model(BaseModel):
    a: MyInt

Model()
#> Model(a=1)

This is explained by the fact that we need to support defaults in type adapters:

TypeAdapter(Annotated[int, Field(default=1)]).get_default_vaue()
#> Some(1)

And as a consequence it accidentally worked for models as well. However, things are inconsistent:

type MyInt = Annotated[int, Field(default=1)]

class Model(BaseModel):
    a: MyInt

Model.model_fields['a'].is_required()  # True

and JSON Schema generation is also acting weirdly: #12024.

Imo, I think we should keep the warning for default and default_factory. Sure, validation behavior still works, but it is a footgun for the reasons mentioned above. Users can still ignore the warning if they feel like it.

I've reached out to the FastAPI team regarding the failing tests. They will need to address them in some way.

Viicos · 2025-06-30T17:36:38Z

-def _warn_on_nested_alias_in_annotation(ann_type: type[Any], ann_name: str) -> None:
-    FieldInfo = import_cached_field_info()
-
-    args = getattr(ann_type, '__args__', None)
-    if args:
-        for anno_arg in args:
-            if typing_objects.is_annotated(get_origin(anno_arg)):
-                for anno_type_arg in _typing_extra.get_args(anno_arg):
-                    if isinstance(anno_type_arg, FieldInfo) and anno_type_arg.alias is not None:
-                        warnings.warn(
-                            f'`alias` specification on field "{ann_name}" must be set on outermost annotation to take effect.',
-                            UserWarning,
-                        )
-                        return


This was fragile logic implemented a long time ago, that is now fully covered by the new warning.

Viicos · 2025-06-30T17:37:55Z

+        with warnings.catch_warnings():
+            # We kind of abused `Field()` default factories to be able to specify
+            # the `defaultdict`'s `default_factory`. As a consequence, we get warnings
+            # as normally `FieldInfo.default_factory` is unsupported in the context where
+            # `Field()` is used and our only solution is to ignore them (note that this might
+            # wrongfully ignore valid warnings, e.g. if the `value_type` to a PEP 695 type alias


This is referring to the following use case:

class Model(BaseModel): a: defaultdict[int, Annotated[list[int], Field(default_factory=lambda: MyList())]]

Viicos · 2025-06-30T17:39:21Z

+                # Because we pass `field` as metadata above (required for attributes relevant for
+                # JSON Scheme generation), we need to ignore the potential warnings about `FieldInfo`
+                # attributes that will not be used:
+                check_unsupported_field_info_attributes=False,


This is for validated function calls (see test_unsupported_field_attribute_nested_with_function()). We don't want to raise a warning for:

@validate_call def func(a: Annotated[int, Field(alias='b')]): ...

github-actions · 2025-06-30T17:41:52Z

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
pydantic
functional_validators.py
warnings.py
pydantic/_internal
_fields.py
_generate_schema.py
Project Total

_{This report was generated by python-coverage-comment-action}

codspeed-hq · 2025-06-30T17:44:16Z

CodSpeed Performance Report

Merging #12028 will not alter performance

_{Comparing field-info-attr-warning (705951a) with main (dac3c43)}

Summary

✅ 46 untouched benchmarks

cloudflare-workers-and-pages · 2025-06-30T19:20:59Z

Deploying pydantic-docs with Cloudflare Pages

Latest commit:	`705951a`
Status:	✅ Deploy successful!
Preview URL:	https://e6f68bfe.pydantic-docs.pages.dev
Branch Preview URL:	https://field-info-attr-warning.pydantic-docs.pages.dev

View logs

Viicos · 2025-07-01T15:56:22Z

I'm wondering if, similar to usage errors, we should link to a new documentation section about warnings, to show examples of this issue.

DouweM · 2025-07-01T17:24:40Z

@Viicos If we haven't documented yet that this is unsupported, I agree we should

Viicos · 2025-07-01T18:23:12Z

Well it is documented, but I was thinking about linking to the docs from the warning message, so that users don't get confused when they see it.

DouweM · 2025-07-01T18:57:34Z

@Viicos Ah I like that!

Viicos · 2025-07-05T10:10:48Z

@Viicos Ah I like that!

Actually this is going to be a bit hard to implement as is, as we'll need to set up the same logic as for errors (that is, construct the URL from the current version, etc). I improved the warning message and we can revisit if users still get confused.

kamzil · 2025-10-31T09:22:29Z

Any pointers on how to get rid of these warnings? We're getting hundreds of them in our project after updating to pydantic 2.12, and it's not really clear what they are about. Is Field not supposed to be used together with Annotated? Any proposed workarounds documented somewhere?

Viicos · 2025-10-31T09:36:17Z

@kamzil

The OP of this PR shows the two cases where the warning will be emitted. If you are using FastAPI, you can try upgrading to >=0.118.1.

kamzil · 2025-10-31T11:02:42Z

Thanks for the pointer to update fastapi. Even after updating to the latest version the warnings remain. I did some more digging, and this only seems to happen in test cases where we're using some fastapi routers. Strangely the warnings are output for each field used in the model that's set as request or some other dependency in the router. So could be still related to fastapi.

Viicos · 2025-10-31T11:06:29Z

Interesting. I assume your code is closed source, but maybe you could paste the traceback when the warning is raised (which should be treated as an error by pytest)? So that I can see where in the FastAPI code this is happening.

kamzil · 2025-10-31T11:32:35Z

Here's a minimal example to reproduce:
mytest.py:

from typing import Annotated

import pytest
from fastapi import FastAPI, Query
from fastapi.testclient import TestClient
from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel


class BaseModelCamelCase(BaseModel):
    model_config = ConfigDict(alias_generator=to_camel)


class MyModel(BaseModelCamelCase):
    a: str

app = FastAPI()

@app.get("/a")
async def endpoint(request: Annotated[MyModel, Query()]): ...

client = TestClient(app, raise_server_exceptions=True)

@pytest.mark.asyncio
async def test_a():
    client.get("/a", params={"a": "test"})

With this, I get this output with pytest mytest.py:

mytest.py::test_a
  .venv/lib/python3.12/site-packages/pydantic/_internal/_generate_schema.py:2249: UnsupportedFieldAttributeWarning: The 'alias' attribute with value 'a' was provided to the `Field()` function, which has no effect in the context it was used. 'alias' is field-specific metadata, and can only be attached to a model field using `Annotated` metadata or by assignment. This may have happened because an `Annotated` type alias using the `type` statement was used, or if the `Field()` function was attached to a single member of a union type.
    warnings.warn(

mytest.py::test_a
  .venv/lib/python3.12/site-packages/pydantic/_internal/_generate_schema.py:2249: UnsupportedFieldAttributeWarning: The 'validation_alias' attribute with value 'a' was provided to the `Field()` function, which has no effect in the context it was used. 'validation_alias' is field-specific metadata, and can only be attached to a model field using `Annotated` metadata or by assignment. This may have happened because an `Annotated` type alias using the `type` statement was used, or if the `Field()` function was attached to a single member of a union type.
    warnings.warn(

mytest.py::test_a
  .venv/lib/python3.12/site-packages/pydantic/_internal/_generate_schema.py:2249: UnsupportedFieldAttributeWarning: The 'serialization_alias' attribute with value 'a' was provided to the `Field()` function, which has no effect in the context it was used. 'serialization_alias' is field-specific metadata, and can only be attached to a model field using `Annotated` metadata or by assignment. This may have happened because an `Annotated` type alias using the `type` statement was used, or if the `Field()` function was attached to a single member of a union type.

If I change MyModel to inherit BaseModel instead of BaseModelCamelCase, the warnings go away.

Viicos · 2025-10-31T11:56:16Z

Are you sure you correctly upgraded to the FastAPI version I mentioned? I get the warning on <0.118.1, but not on >=0.118.1.

kamzil · 2025-10-31T12:03:43Z

Must have had some leftovers from the old fastapi or its related libs in my venv, as nuking the whole environment worked. No more warnings. Sorry for the noise.

Viicos added 5 commits June 30, 2025 19:15

Reorganize core schema generation warnings

68663aa

Add UnsupportedFieldAttributeWarning

59a9516

Emit warning when field attributes are used in invalid contexts

59872ae

Remove old and fragile logic that implemented the warning

fe48724

Update and add tests

c3e105f

github-actions Bot added the relnotes-fix Used for bugfixes. label Jun 30, 2025

Viicos commented Jun 30, 2025

View reviewed changes

Comment thread pydantic/_internal/_generate_schema.py Outdated

Viicos requested review from DouweM and davidhewitt June 30, 2025 17:40

Viicos added relnotes-change Used for changes to existing functionality which don't have a better categorization. needs-blogpost-entry This PR needs to be documented in the release notes blog post and removed relnotes-fix Used for bugfixes. labels Jun 30, 2025

Viicos mentioned this pull request Jun 30, 2025

JSON Schema inconsistently sets Annotated type aliases as required or not #12024

Closed

1 task

Viicos added the third-party-tests Add this label on a PR to trigger 3rd party tests label Jun 30, 2025

Viicos closed this Jun 30, 2025

Viicos reopened this Jun 30, 2025

Cope with FastAPI

6b7f8dd

Fix implementation

6c868fa

Viicos force-pushed the field-info-attr-warning branch from 59be012 to 6c868fa Compare June 30, 2025 20:04

DouweM requested changes Jul 1, 2025

View reviewed changes

Comment thread pydantic/_internal/_generate_schema.py Outdated

Comment thread pydantic/_internal/_generate_schema.py Outdated

Comment thread pydantic/_internal/_generate_schema.py Outdated

Feedback

30acc55

Viicos force-pushed the field-info-attr-warning branch from 91fc505 to 30acc55 Compare July 1, 2025 15:04

Improve warning message

705951a

Viicos force-pushed the field-info-attr-warning branch from b87d649 to 705951a Compare July 5, 2025 10:21

DouweM approved these changes Jul 17, 2025

View reviewed changes

Viicos merged commit 3a7fe26 into main Jul 18, 2025
85 of 90 checks passed

Viicos deleted the field-info-attr-warning branch July 18, 2025 08:22

cjwatson mentioned this pull request Sep 18, 2025

👽️ Ensure compatibility with Pydantic 2.12.0 fastapi/fastapi#14036

Merged

dgw mentioned this pull request Oct 8, 2025

New warning from pydantic 2.12 at load time MarshalX/atproto#625

Closed

anishathalye mentioned this pull request Oct 20, 2025

Fix invalid use of field-specific metadata run-llama/llama_index#20122

Merged

Viicos mentioned this pull request Oct 31, 2025

Warning about 'alias' being unused in the Field() function in specific contexts seems wrong #12362

Closed

1 task

Uh oh!

Conversation

Viicos commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Viicos Jun 30, 2025

Choose a reason for hiding this comment

Uh oh!

Viicos Jun 30, 2025

Choose a reason for hiding this comment

Uh oh!

Viicos Jun 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented Jun 30, 2025

Coverage report

Uh oh!

codspeed-hq Bot commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #12028 will not alter performance

Summary

Uh oh!

cloudflare-workers-and-pages Bot commented Jun 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying pydantic-docs with Cloudflare Pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Viicos commented Jul 1, 2025

Uh oh!

DouweM commented Jul 1, 2025

Uh oh!

Viicos commented Jul 1, 2025

Uh oh!

DouweM commented Jul 1, 2025

Uh oh!

Viicos commented Jul 5, 2025

Uh oh!

Uh oh!

kamzil commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Viicos commented Oct 31, 2025

Uh oh!

kamzil commented Oct 31, 2025

Uh oh!

Viicos commented Oct 31, 2025

Uh oh!

kamzil commented Oct 31, 2025 • edited by Viicos Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Viicos commented Oct 31, 2025

Uh oh!

kamzil commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Viicos commented Jun 30, 2025 •

edited

Loading

codspeed-hq Bot commented Jun 30, 2025 •

edited

Loading

cloudflare-workers-and-pages Bot commented Jun 30, 2025 •

edited

Loading

kamzil commented Oct 31, 2025 •

edited

Loading

kamzil commented Oct 31, 2025 •

edited by Viicos

Loading