Pydantic v2: 'PydanticUserError: X is not fully defined; you should define Y, then call X.model_rebuild()' (unresolved forward reference), stricter since 2.10/2.11

Cause: a model annotation references a type that is not defined when the class is built — a forward reference (string annotation), a recursive/self-referential model, or a type defined later or in another module with a circular import. Pydantic v2 cannot finish generating the core schema. Pydantic 2.10/2.11 made lazy resolution stricter, so cases that previously auto-resolved now require an explicit rebuild. Recommended action: 1) After the referenced types are defined, call `X.model_rebuild()` (e.g. at the bottom of the module once all referenced models exist). In v2, `model_rebuild()` replaced v1's `update_forward_refs()`. 2) For circular dependencies across files: import all involved models in one place (a package `__init__` or a small registry) and call `model_rebuild()` there AFTER everything is imported; if symbols still aren't found, pass a namespace: `Model.model_rebuild(_types_namespace={...})` (and `force=True` when needed). 3) Rebuilding the OUTERMOST model builds the whole nested schema, so every nested type must be importable/defined before that call. Distinct related cause (do NOT conflate): `PydanticUserError` also arises from an incomplete v1->v2 migration — a `@validator` without the v2 signature (use `@field_validator`), a removed `class Config` key (use `model_config = ConfigDict(...)`), or `allow_reuse`. That is a different cause of the same exception type; read the `errors.pydantic.dev` code in the message to tell them apart. Misleading approaches: reordering class definitions alone when a true circular import exists; assuming a pydantic bug; pinning an old pydantic to 'fix' it instead of adding the rebuild call. Version/fix status: intended v2 behavior, stricter since 2.10/2.11. Downgrading (e.g. to 2.10.1) resolved some regressions in reports, but the durable fix is an explicit `model_rebuild()`. Sources: - https://docs.pydantic.dev/latest/errors/usage_errors/#class-not-fully-defined - https://docs.pydantic.dev/latest/concepts/models/#rebuilding-model-schema - https://github.com/pydantic/pydantic/discussions/11776 Unknowns: whether a given failure is a forward-ref/rebuild case vs a migration user-error — check the error code and whether a `model_rebuild()` resolves it. Evidence boundary: official Pydantic docs + a public GitHub discussion; no independent reproduction claimed here.