First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

also on Github at https://github.com/mtblanton/fastapi-form-list-repro

from typing import Annotated, Literal

from fastapi import FastAPI, Form
from pydantic import BaseModel

app = FastAPI()


class InputWithList(BaseModel):
    type: Literal["list"] = "list"
    list: list[str]


class InputWithoutList(BaseModel):
    type: Literal["no-list"] = "no-list"
    single: str


@app.post("/test-union")
def test_form_list_with_union(
    request: Annotated[InputWithList | InputWithoutList, Form(discriminator="type")],
):
    return request


@app.post("/test-no-union")
def test_form_list_without_union(
    request: Annotated[InputWithList, Form(discriminator="type")],
):
    return request

Description

The Form parsing, mapping, and validation runs into trouble when these conditions are combined:

• The Form type is defined as a union
• The input type being validated has a list field
• The request field for that list field only has one element

Call an endpoint with a single form value for list

curl --request POST \
  --url http://localhost:8000/test-union \
  --header 'content-type: multipart/form-data' \
  --form type=list \
  --form list=foo

I expect a response of

{
  "type": "list",
  "list": [
    "foo"
  ]
}

I get a validation error instead:

{
  "detail": [
    {
      "type": "list_type",
      "loc": [
        "body",
        "list",
        "list"
      ],
      "msg": "Input should be a valid list",
      "input": "foo"
    }
  ]
}

This is not an issue when calling the endpoint with multiple items for list:

curl --request POST \
  --url http://localhost:8000/test-union \
  --header 'content-type: multipart/form-data' \
  --form type=list \
  --form list=foo \
  --form list=foo2

Or when calling an endpoint that doesn't use a union:

curl --request POST \
  --url http://localhost:8000/test-no-union \
  --header 'content-type: multipart/form-data' \
  --form type=list \
  --form list=foo

Operating System

macOS

Operating System Details

M2 Macbook Pro on Tahoe 26.2

FastAPI Version

0.135.1

Pydantic Version

2.12.5

Python Version

3.14.2

Additional Context

I stepped through FastAPI code a bit in the debugger to see if it was something I could work around with different types but didn't find anything. My guess is that utils._extract_form_body or utils.request_body_to_args don't know what to do with Union types! When it was parsing a non-union request it was transforming the single value into a list before sending it to the validator. When it was parsing a union type it wasn't doing that handling.