🐛 Support Annotated in stream return annotations for JSONL and SSE - #16348

Pull Request

Discussion: #16337

Description

Fixes #16334

Problem

Wrapping an async stream return annotation (e.g. AsyncIterator[T], AsyncIterable[T], or AsyncGenerator[T, None]) in typing.Annotated causes route registration to raise FastAPIError: Invalid args for response field! at application startup:

@app.get("/stream")
async def stream() -> Annotated[AsyncIterator[Item], "metadata"]:
    yield Item(name="foo")

This occurs because get_stream_item_type() in fastapi/dependencies/utils.py checks whether get_origin(annotation) is in _STREAM_ORIGINS. Because the outermost origin of Annotated[...] is Annotated, get_stream_item_type returns None. FastAPI then erroneously falls back to treating the entire streaming iterator annotation as a single HTTP response model, which Pydantic cannot serialize as a field.

Solution

Unwrap Annotated layers in get_stream_item_type before evaluating against _STREAM_ORIGINS:

def get_stream_item_type(annotation: Any) -> Any | None:
    while get_origin(annotation) is Annotated:
        annotation = get_args(annotation)[0]
    origin = get_origin(annotation)
    if origin is not None and origin in _STREAM_ORIGINS:
        type_args = get_args(annotation)
        if type_args:
            return type_args[0]
        return Any
    return None

This restores complete parity between unwrapped AsyncIterator[T] and Annotated[AsyncIterator[T], ...]:

• Routes register and run successfully.
• Yielded stream items are validated against the extracted item type T.
• OpenAPI schema generation correctly emits itemSchema for both application/jsonl and text/event-stream (SSE).

Tests

Added comprehensive test coverage in tests/test_stream_annotated.py:

• test_get_stream_item_type_unwraps_annotated: Unit tests verifying get_stream_item_type unwrap behavior with single and nested Annotated types, sync/async iterators, and non-stream types.
• test_stream_annotated_jsonl: End-to-end JSON Lines streaming with Annotated[AsyncIterator[Item], "metadata"].
• test_stream_nested_annotated_jsonl: Nested Annotated wrappers.
• test_stream_annotated_async_generator: AsyncGenerator.
• test_stream_annotated_sync: Synchronous Iterator.
• test_stream_annotated_sse: Server-Sent Events with EventSourceResponse.
• test_router_stream_annotated: Streaming route included through APIRouter.
• test_stream_annotated_openapi_schema: Verifying generated OpenAPI itemSchema for JSONL and SSE endpoints.

All 8 new tests fail on master with FastAPIError and pass cleanly with this fix. The existing stream and SSE test suites (67 tests) pass without regression, and all prek pre-commit hooks pass.

AI Disclaimer

Prompt: Diagnose issue #16334 / discussion #16337 in FastAPI regarding Annotated stream return annotations, implement the fix in get_stream_item_type, add comprehensive tests, and ensure all tests and linters pass.
Model: Gemini 3.8 Flash

Checklist

• This PR links to a GitHub Discussion for the proposed code change.
• I added tests for the change.
• The new or updated tests fail on the main branch and pass on this PR.
• Coverage stays at 100%.
• The documentation explains the change if needed.