Temporal response is ignored when an exception is raised

[textbook]

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

from http import HTTPStatus
from typing import Optional

from fastapi import Depends, FastAPI, Header, HTTPException, Response
from typing_extensions import Annotated


def request_id(
    response: Response,
    request_correlation_id: Annotated[Optional[str], Header()] = None,
) -> None:
    if request_correlation_id is not None:
        response.headers.append("Request-Correlation-Id", request_correlation_id)


app = FastAPI(dependencies=[Depends(request_id)])


@app.get("/success")
def _() -> None:
    pass


@app.get("/failure")
def _() -> None:
    raise HTTPException(status_code=HTTPStatus.INTERNAL_SERVER_ERROR)

Description

Making a GET request to /success correctly propagates the Request-Correlation-Id header to the response, but on /failure the header is not propagated. This happens consistently in Python 3.8-3.13 as demonstrated in https://github.com/textbook/fastapi-bug.

Operating System

macOS

Operating System Details

Using macOS locally, but replicated in Ubuntu in GitHub Actions and originally noticed on a Windows machine.

FastAPI Version

0.115.6

Pydantic Version

2.10.4

Python Version

3.8.20

Additional Context

Although I ticked the box:

After submitting this, I commit to one of:

• Read open questions until I find 2 where I can help someone and add a comment to help there.
• I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future.
• Review one Pull Request by downloading the code and following all the review process.

I'm probably not going to do that. I'm already active on Stack Overflow, and reporting a bug not asking a question as such.

[textbook]

As suggested in #7791, a possible workaround is to add something like:

@app.exception_handler(StarletteHTTPException)
async def _(request: Request, exc: StarletteHTTPException):
    if exc.headers is None:
        exc.headers = dict()
    if (
        request_correlation_id := request.headers.get("Request-Correlation-Id")
    ) is not None:
        exc.headers["Request-Correlation-Id"] = request_correlation_id
    return await http_exception_handler(request, exc)

However, this means duplicating the logic for updating the temporal response, which seems awkward and may be challenging where this is done on a per-path-operation basis.

[PREPONDERANCE]

I believe a better workaround would be to register the custom exception handler in main.py, something analogous to this:

from fastapi import HTTPException
from fastapi.responses import JSONResponse
from fastapi.encoders import jsonable_encoder

async def http_exception_handler(request: Request, exc: HTTPException):
    return JSONResponse(status_code=exc.status_code, content=jsonable_encoder(exc.detail))


async def internal_exception_handler(request: Request, exc: Exception):
    # Some custom error handling
    pass

app.add_exception_handler(HTTPException, http_exception_handler)
app.add_exception_handler(500, internal_exception_handler)

In which the HTTPException is a wrapper around StarletteHTTPException (I generally avoid directly importing the Starlette classes).

[textbook]

Perhaps I'm missing something, but I don't see how that's different. It certainly doesn't seem to fix the underlying problem (temporal response changes being ignored). The import from Starlette was based on the docs, per the linked discussion:

...when you register an exception handler, you should register it for Starlette's HTTPException.

[Kludex]

#4488 (comment)

[textbook]

Perhaps this should be a separate discussion - whether or not I proposed the optimal exception handler, the issue at hand here is the temporal response.

[Kludex]

You should probably be using a middleware for this, not relying on the response object.

The current behavior seems fine to me.

[textbook]

Middleware would work to a certain extent¹; for example, in this case:

@app.middleware("http")
async def propagate_request_id(request: Request, call_next):
    response = await call_next(request)
    if (
        request_correlation_id := request.headers.get("Request-Correlation-Id")
    ) is not None:
        response.headers["Request-Correlation-Id"] = request_correlation_id
    return response

---

But in what sense is it fine? I've injected a temporal response, as documented, added a header, and then it's simply vanished.

The use of an app-level dependency and HTTPException was specific to the case in which the behaviour was originally identified, but it's not isolated to this; it's the same if the temporal response is injected into the path operation function, for example, and applies to any error that's thrown.

If this behaviour is expected, or at least tolerated, it would be helpful for the documentation to note each time it refers to the temporal response that this will be ignored in the case that an error is thrown (i.e. although a response will be sent, it will not include any header and/or cookie set on the temporal response, unless the path operation function goes through its happy path).

---

¹ It seems that you can't safely handle any error in the middleware, but if the transport layer ensures every possible failure becomes an HTTPException this will suffice.