Why does a FastAPI 0.143 log-tail path operation that raises HTTPException(404) before its first yield send clients a 200 and a broken body?
answer
- calling a generator runs nothing
- status line goes out first
- dependencies run before the response
- errors after start become disconnects
basics
~20 sA yielding path operation's body, even the code before its first yield, runs only when the stream is iterated, after the 200 status and headers are sent. Raise the 404 from a dependency, which FastAPI solves before the response starts.
solid answer
~40 sBecause the function contains `yield`, calling it only creates a generator. FastAPI wraps that generator in a streaming response, and Starlette sends `http.response.start` with status 200 before asking for the first item. So the check before the first `yield` runs after the status is committed; the `HTTPException` reaches the exception middleware, which raises `RuntimeError: Caught handled exception, but response already started.`, and Uvicorn logs the error and closes the connection mid-body. The fix is to move the check into a dependency: dependencies are solved before the response object exists, so a 404 there is a real 404. The same timing ignores status or header changes made on a `Response` parameter inside the generator.
code
python · 29 linesfrom collections.abc import AsyncIterable
from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException
from pydantic import BaseModel
app = FastAPI()
LOGS = {"api": ["started", "ready"]}
class LogEntry(BaseModel):
message: str
def existing_log(name: str) -> list[str]:
# A dependency is solved before the response starts,
# so this 404 still reaches the client as a 404.
if name not in LOGS:
raise HTTPException(status_code=404, detail="Log not found")
return LOGS[name]
@app.get("/logs/{name}/tail")
async def tail_log(
lines: Annotated[list[str], Depends(existing_log)],
) -> AsyncIterable[LogEntry]:
for line in lines:
yield LogEntry(message=line)go deeper
Remember that a FastAPI path operation with yield does not run its body until the stream starts, after the status is sent.
Walk through the order: dependencies solved, generator created, response started, first item pulled, and say which step can still choose the status.
Diagnose the 200-with-cut-body symptom from the RuntimeError in the logs, move checks into dependencies, and design an in-band error item for failures that can only happen mid-stream.
Set the team rule for streaming endpoints: preconditions in dependencies, an in-band error and end-of-stream contract, and metrics that count broken streams, not just status codes.
## Why the status is already sent The puzzle comes from Python and FastAPI together. A function that contains `yield` anywhere is a **generator function**: calling it does not run its body, it only creates a generator object. The body starts running when someone asks for the first item. For a yielding path operation in **FastAPI 0.143**, the order of events is: 1. FastAPI parses the request and **solves the dependencies** (path, query and body parameters, `Depends` callables). 2. It calls the path operation function, which returns a generator without executing any of its lines. 3. It wraps the generator in a streaming response (JSON Lines by default, Server-Sent Events with `EventSourceResponse`), taking the status code from the decorator's `status_code` or a `Response` parameter at this moment. 4. Starlette's `StreamingResponse` sends the ASGI `http.response.start` message, carrying the status and headers. 5. Only now does it pull the first item, so the generator body runs from the top, including the `if name not in LOGS: raise HTTPException(404)` check. By step 5 the status line is on the wire. The `HTTPException` propagates to Starlette's exception middleware, which would normally turn it into a `404` response, but it finds that a response has already started and raises instead: ``` RuntimeError: Caught handled exception, but response already started. ``` ## What the client and the server see | Where | What appears | |---|---| | client | status `200`, `Content-Type: application/jsonl`, then the connection closes before the body completes | | server log | Uvicorn's `Exception in ASGI application` with the `RuntimeError` above | | monitoring | a request recorded as `200`, so status-based error rates miss it | The last row is the operational cost: the failure is invisible to anything that counts responses by status code. In-process tests are kinder: `fastapi.testclient.TestClient`, with its default settings, re-raises the `RuntimeError` inside the test instead of returning a response, so a test that requests an unknown log name exposes the bug at once. A test that only exercises the happy path never sees it, which is how this tends to reach production. ## How to fix it - **Move the check into a dependency.** A function such as `existing_log(name: str)` that raises `HTTPException(status_code=404)` runs in step 1, before any response exists, so the client receives a normal `404` with `{"detail": "Log not found"}`. The dependency can also return the opened resource, so the generator just iterates. - **Use parameter validation** for checks that are about the input's shape, such as `Annotated[int, Query(ge=1)]`. Those failures become a `422` before the stream starts. - **Set status and headers through the decorator or before the generator runs.** Setting `response.status_code` or `response.headers[...]` on a `Response` parameter inside the generator body has no effect, because FastAPI already copied them when it built the response. - **Return a response instead of yielding** when the decision needs async work you do not want in a dependency: an ordinary function can check first and then `return` a response built from an inner generator. This loses per-item validation. ## Errors that can only happen mid-stream Some failures cannot be moved earlier: the model times out after ten tokens, a yielded item fails its model's validation (`ResponseValidationError`), or the log file is rotated away. For those the status cannot change any more, so the stream needs an **in-band** error convention: 1. Catch the expected exception inside the generator. 2. Yield a final item that says so: an error object as the last JSON line, or `ServerSentEvent(data={"message": "..."}, event="error")` on an SSE stream. 3. Return normally, so the client sees a clean end rather than a cut connection. Unexpected exceptions will still end the stream abruptly, which is why clients of a streaming endpoint should treat an unterminated stream as a failure. ## The release detail behind the status code Since **0.140.13**, a `status_code` given on the decorator is honoured by JSON Lines and SSE endpoints; the release notes record that earlier releases ignored it on those streams. The rule above about timing is unchanged: whatever status is chosen, it is chosen before the generator body runs.
- Inside a FastAPI yielding path operation, can you set response.status_code = 206 on a Response parameter?Not from the generator body. FastAPI reads the `Response` parameter's status and headers when it builds the streaming response, before the body runs, so a change made inside the generator is ignored. Set the status on the decorator, or in a dependency that receives the same `Response` parameter.
- How should a FastAPI SSE token stream report a model timeout that happens halfway through?The 200 is already sent, so report it in-band: catch the timeout in the generator, yield `ServerSentEvent(data={"message": "model timed out"}, event="error")`, and return. The browser gets a named error event and a clean end instead of a dropped connection it might retry.
- Code before the first yield runs when the path operation function is called.
- Raising HTTPException anywhere in a streaming endpoint still produces its status code.
- Setting response.status_code inside the generator changes the streamed response's status.
- A mid-stream ResponseValidationError turns the response into a 500.
- Status-code dashboards will catch errors raised inside a stream.
Assumes FastAPI 0.143; yield path operations stream since 0.134, and a decorator status_code is honoured on JSON Lines and SSE streams since 0.140.13.