FastAPI OpenAPI schema generation error in CI

FastAPI builds an OpenAPI schema from your route signatures. If a parameter or response uses a type it cannot represent as a Pydantic field, generation fails at startup or when a test requests /openapi.json, with a message pointing at the offending type.

What this error means

A test that calls the docs or /openapi.json, or app startup, fails with "fastapi.exceptions.FastAPIError: Invalid args for response field" naming a type such as a plain class or an un-annotated dependency return.

fastapi.exceptions.FastAPIError: Invalid args for response field! Hint: check that
<class 'app.models.Item'> is a valid Pydantic field type.

Common causes

A non-Pydantic type used where FastAPI expects a field

A route returns or accepts a plain class or ORM model directly as the schema type, which FastAPI cannot express as a field.

A generic or forward reference OpenAPI cannot resolve

An unresolved forward reference or an unsupported generic leaves FastAPI unable to build the field for the schema.

How to fix it

Use Pydantic models for request and response types

1. Read the FastAPIError hint to find the offending type.
2. Replace the raw class with a Pydantic schema in the annotation.
3. Request /openapi.json in a test to confirm the schema builds.

from app.schemas import ItemOut

@app.get("/items/{id}", response_model=ItemOut)
def read_item(id: int):
    ...

Add a schema smoke test

Hit the OpenAPI endpoint in CI so any route with an unrepresentable type fails immediately.

def test_openapi_builds(client):
    assert client.get("/openapi.json").status_code == 200

How to prevent it

• Annotate request and response types with Pydantic models.
• Resolve forward references before they reach a route signature.
• Keep a CI test that fetches /openapi.json.

Related guides