CORS Middleware and exception handler

[xdewx]

the MRE is at https://github.com/4tst/mre-exception-handler.

without @exception_handler(ValueError), then will appear CORS error when router raise ValueError,
for more detail, please click here

What's actually bothering me is FastAPI's error handling mechanism—why does it allow middleware to cause counterintuitive issues? Besides going to the trouble of understanding the internal mechanics, can FastAPI avoid such problems in a more elegant and intuitive way?

[YuriiMotov]

The MRE is unnecessarily complex. You can showcase this without sub-router

[xdewx]

you are right. let me simplify the code.

[xdewx]

Thanks for the clear example! If that's the case, FastAPI can use the combination of "module id + function name" for naming to avoid such issues, but why not?

[xdewx]

And in my side, different function name makes no difference. CORS stills.

we need make it clear, what i want is no need ValueError or AssertionError handler but only @app.exception_handler(Exception)

[YuriiMotov]

MRE

Here is a MRE implemented in form of test (in the details):

Details

import pytest
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from starlette.testclient import TestClient

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)


@app.exception_handler(Exception)
async def exception_handler(request, ex):
    return JSONResponse(content={"success": False})


@app.exception_handler(AssertionError)
# @app.exception_handler(ValueError)  # <= Uncommenting this line will make both tests pass
async def value_error_exception_handler(request, ex):
    return JSONResponse(content={"success": False})


@app.post("/test1")
async def ep_1():
    assert "a" == "b"


@app.post("/test2")
async def ep_2():
    raise ValueError("Invalid value")


@pytest.mark.parametrize(
    "url",
    [
        "/test1",
        "/test2",
    ],
)
def test_cors_headers(url: str):
    headers = {
        "Origin": "https://localhost.tiangolo.com",
        "Access-Control-Request-Method": "GET",
        "Access-Control-Request-Headers": "X-Example",
    }

    client = TestClient(app, raise_server_exceptions=False)
    resp = client.post(url, headers=headers)
    assert resp.status_code == 200
    assert "access-control-allow-origin" in resp.headers

What is happening here:

• We set 2 exception handlers:
  • 1 - For Exception class
  • 2 - For AssertionError class
• The endpoint /test1 raises AssertionError
• The endpoint /test2 raises ValueError
• When we test both endpoints, providing the same headers
  • /test1 returns response with access-control-allow-origin set
  • /test2 doesn't have access-control-allow-origin response header

Why this is happening

This is because AssertionError is handled by ExceptionMiddleware (that is inner-most middleware in stack), but ValueError is handled by ServerErrorMiddleware (that is outer-most middleware in stack).
This happens because Exception class has special meaning for FastAPI (Starlette). It's like "all unhandled exeptions" and they are treated by FastAPI as server errors.

And, as your response is sent by outer-most middleware (ServerErrorMiddleware), other middlewares (CORSMiddleware specifically) can't intercept and modify it.

If you want to make your exception handled by ExceptionMiddleware instead of ServerErrorMiddleware, you should specify more specific exception class.
This way, the response will be sent by ExceptionMiddleware (inner-most middleware) and it will be successfully modified by CORSMiddleware (CORS headers will be added).

So, this is why setting the exception handler for ValueError changes the behavior (both tests will pass).

Solution

The fact that CORSMiddleware doesn't set CORS headers for server errors is well-known.
In Starlette docs it's suggested to wrap you whole app with CORSMiddleware.
It works with FastAPI app as well (see code in the details):

Details

import pytest
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse
from starlette.testclient import TestClient

app = FastAPI()


@app.exception_handler(Exception)
async def exception_handler(request, ex):
    return JSONResponse(content={"success": False})


@app.exception_handler(AssertionError)
async def value_error_exception_handler(request, ex):
    return JSONResponse(content={"success": False})


@app.post("/test1")
async def ep_1():
    assert "a" == "b"


@app.post("/test2")
async def ep_2():
    raise ValueError("Invalid value")


# Important to wrap our app by CORSMiddleware after adding all endpoints and exception handlers
app = CORSMiddleware(
    app=app,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)


@pytest.mark.parametrize(
    "url",
    [
        "/test1",
        "/test2",
    ],
)
def test_cors_headers(url: str):
    headers = {
        "Origin": "https://localhost.tiangolo.com",
        "Access-Control-Request-Method": "GET",
        "Access-Control-Request-Headers": "X-Example",
    }

    client = TestClient(app, raise_server_exceptions=False)
    resp = client.post(url, headers=headers)
    assert resp.status_code == 200
    assert "access-control-allow-origin" in resp.headers

[xdewx]

Regarding CORS errors, the steps you mentioned can be used to resolve them. However, from a design perspective, shouldn't such issues not be left for users to fix? After all,  Exception  is the base class for all exceptions, so it should logically include  ValueError  and  AssertionError —this is more intuitive.

[YuriiMotov]

After all, Exception is the base class for all exceptions, so it should logically include ValueError and AssertionError —this is more intuitive.

I don't understand why you are saying this.
Exception indeed includes ValueError and AssertionError. And FastAPI doesn't break this. As you can see, your ValueError is handled by exception handler decorated with @app.exception_handler(Exception) (notice the status code of response is 200 - it would be 500 if it was not handled by that handler).

---

I agree that current design is not ideal.
But just allowing ExceptionMiddleware to catch all exceptions (so that @app.exception_handler(Exception) would set handler for ExceptionMiddleware instead of ServerErrorMiddleware) would not solve this - it wouldn't catch exceptions raised by other user middlewares. So, it will still be just partial solution.

Maybe we can solve this by integrating CORSMiddleware into FastAPI (Starlette), so that it would be able to intercept any responses sent by app, including those that are sent by ServerErrorMiddleware.

This way in user code we will not need to include CORSMiddleware, but will just configure it like this:

app = FastAPI()
app.cors.config.allow_origins = ["*"]
app.cors.config.allow_credentials = True
app.cors.config.allow_methods = ["*"]
app.cors.config.allow_headers = ["*"]

[xdewx]

Please allow me to make a bold assumption: if the exception handling middleware is registered as the last one, can it catch all exceptions? Moreover, is there any compelling reason to distinguish between exception middleware and server error middleware?

From the perspective of current solutions, either using FastAPI's built-in middleware or passing the FastAPI instance into the middleware—essentially, both approaches enable the middleware to access more context for modifying the state of the FastAPI instance. Therefore, could exposing the FastAPI instance to middleware and unifying the middleware registration method also resolve the current issue?

Additionally, you're absolutely right—my expression was not entirely accurate. When only the Exception handler is present, ValueError is indeed intercepted, but due to other middleware, the final effect does not align with expectations.

[YuriiMotov]

if the exception handling middleware is registered as the last one, can it catch all exceptions? Moreover, is there any compelling reason to distinguish between exception middleware and server error middleware?

What do you mean by saying "the last one"?
ExceptionMiddleware is the inner-most, that means it wraps the router (routing, dependency resolution and endpoint execution), but all other middlewares are outside.
ExceptionMiddleware can't catch exceptions raised by other middlewares (they are outside).

From the perspective of current solutions, either using FastAPI's built-in middleware or passing the FastAPI instance into the middleware—essentially, both approaches enable the middleware to access more context for modifying the state of the FastAPI instance. Therefore, could exposing the FastAPI instance to middleware and unifying the middleware registration method also resolve the current issue?

I'm not sure I understand what you mean..
Both approaches, wrapping app with CORSMiddleware and integrating CORSMiddleware into app, are not about "modifying the state of FastAPI instance". They are about the ability to intercept sending the response.

---

Sorry, I think I'm not ready to spend more time on this question right now. I added it to the list of ideas to review later.

If you know how to solve this - please open a PR with your solution. We will review it.

[xdewx]

Thank you for your patient response. There's no rush to fully resolve this issue immediately. Since I don't yet have an in-depth and professional understanding of FASTAPI, some of my remarks are speculative. We can discuss further once there's an implementation plan later.

[wu-clan]

Hi~ @xdewx

You can also check out these related: #7847 #8027