Should Access-Control-Allow-Origin header added to response When Exception Occur?

[timothy-jeong]

[Problem Description]

In the starlette version 0.45.4, When an unhandled exception (i.e., Exception with a 500 status code) occurs in the Starlette Application, even though CORSMiddleware is added and an ExceptionHandler is registered with ServerErrorMiddleware, browsers report CORS errors due to the missing Access-Control-Allow-Origin header in the error response.

you can reproduce this:

from starlette.applications import Starlette
from starlette.middleware.cors import CORSMiddleware
from starlette.requests import Request
from starlette.responses import Response, JSONResponse
from starlette.exceptions import HTTPException
from starlette import status
from starlette.routing import Route

class MyException(Exception):
    def __init__(self, *args):
        super().__init__(*args)


async def health(request):
    return JSONResponse(status_code=status.HTTP_200_OK,content={"message": "healthy"})

async def throws_exception(request):
    raise Exception("Exception")

async def throws_my_exception():
    raise MyException("MyException!")

async def throws_http_exception(request):
    raise HTTPException(
        status_code=status.HTTP_405_METHOD_NOT_ALLOWED,
        detail="HTTPException"
    )


app = Starlette(
    routes=[
        Route("/health", health),
        Route("/exception", throws_exception),
        Route("/exception/my", throws_my_exception),
        Route("/exception/http", throws_http_exception)
    ]
)

app.add_middleware(
    CORSMiddleware, allow_origins=["*"], allow_credentials=False, allow_methods=["*"], allow_headers=["*"]
)
        
@app.exception_handler(MyException)
async def handle_super_exception(req: Request, exc: MyException):
    # any status_code
    return Response(status_code=status.HTTP_402_PAYMENT_REQUIRED,content="MyException Handled")
    
@app.exception_handler(Exception)
async def handle_general_exception(req: Request, exc: Exception):
    return Response(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,content="Exception Handled")

curl -i -X GET -H "Origin: https://google.com" http://127.0.0.1:8000/exception # no Access-Control-Allow-Origin header 
curl -i -X GET -H "Origin: https://google.com" http://127.0.0.1:8000/exception/my # no Access-Control-Allow-Origin header
curl -i -X GET -H "Origin: https://google.com" http://127.0.0.1:8000/exception/http # Access-Control-Allow-Origin exist

[Why This Is a Problem]

From a developer’s perspective, it is confusing and unexpected that adding CORSMiddleware does not guarantee proper CORS headers for error responses.

When handling requests from browser-based clients, unhandled exceptions should still comply with CORS requirements. The absence of the Access-Control-Allow-Origin header can lead to client-side CORS errors, thereby affecting service quality.

[Discussed Solutions]

Previous discussions on this issue have taken place in Starlette’s Issue #617 and in FastAPI’s Discussion. The proposed solutions in those discussions include:

1. Wrapping the Starlette Application in CORSMiddleware:
This forces all responses—including error responses—to pass through CORSMiddleware, ensuring that CORS headers are added.

2. Injecting CORS Headers at the ExceptionHandler Level:
Modifying the ExceptionHandler to include CORS-related headers in the response, regardless of whether the error originated from ExceptionMiddleware or ServerErrorMiddleware.

Need for a New Approach:
While the above solutions are useful, it remains unclear to me whether these workarounds are officially supported by the Starlette framework. The current behavior suggests that when CORSMiddleware is configured, exceptions that fall through to ServerErrorMiddleware do not benefit from the expected CORS behavior. I believe that if adding CORSMiddleware leads to behavior beyond its intended scope, the framework should either restrict its use in the Starlette Application or provide a built-in mechanism to ensure global CORS handling—even for unhandled exceptions.

In my view, CORS settings should apply globally. Relying on ExceptionHandlers to inject CORS headers in error responses feels inconsistent with the idea of global CORS policy enforcement.

[Technical Root Cause]

The technical issue arises from the order in which the middleware chain is constructed during the initialization of the Starlette Application. Because the middleware chain is built such that ServerErrorMiddleware is the outermost layer, exceptions that are not caught by ExceptionMiddleware are directly handled by ServerErrorMiddleware. Consequently, these error responses never pass through CORSMiddleware, resulting in missing CORS headers.

[My Proposal]

Option 1: Codebase Modification
Modify the middleware stack builder so that when building the middleware chain, it checks for the presence of CORSMiddleware in user_middleware. If found, then register the error handler for (500, Exception) with ExceptionMiddleware as well. This approach leverages the existing Starlette conventions with minimal changes to the codebase:

# starlette/applications.py, line 79
def build_middleware_stack(self) -> ASGIApp:
    debug = self.debug
    error_handler = None
    exception_handlers: dict[typing.Any, typing.Callable[[Request, Exception], Response]] = {}

    for key, value in self.exception_handlers.items():
        if key in (500, Exception):
            error_handler = value
        else:
            exception_handlers[key] = value
    
    # If CORSMiddleware is registered, add the (500, Exception) handler to ExceptionMiddleware as well.
    for middleware_to_stack in self.user_middleware:
        # Ensure proper type checking; here we assume CORSMiddleware is imported from starlette.middleware.cors
        if isinstance(middleware_to_stack.cls, CORSMiddleware):
            exception_handlers[Exception] = error_handler

    middleware = (
        [Middleware(ServerErrorMiddleware, handler=error_handler, debug=debug)]
        + self.user_middleware
        + [Middleware(ExceptionMiddleware, handlers=exception_handlers, debug=debug)]
    )

    app = self.router
    for cls, args, kwargs in reversed(middleware):
        app = cls(app, *args, **kwargs)
    return app

Option 2: Official Documentation Tip
Add a tip in the official documentation stating that when using CORSMiddleware, unexpected behavior may occur regarding error responses. Provide guidance on the two solutions discussed above so that developers can work around the issue if necessary.

---

Call for Feedback

I am eager to submit a PR addressing this issue, but I would appreciate hearing other opinions and verifying that I haven't overlooked any important details.

[timothy-jeong]

Additional Considerations for Option 1

For more detail, the Option 1 code is not perfect—it will produce an error if error_handler is None. Moreover, if error_handler is not set, the browser will still generate CORS errors.

[Kludex]

Wrapping the app with the cors middleware is the official recommendation. PR welcome to improve docs.

[timothy-jeong]

thank you again

[LewisCowlesMotive]

Okay but this isn't just specific to CORS. Any response modification, such as the request timings shown in docs really should be kicked out to the edge, like the CORS handler is, so that they can modify responses.