skip to content

In FastAPI, what happens when a function queued with BackgroundTasks.add_task raises an exception after the response was sent?

level: seniorimportance: should knowfreq 35%

answer

  1. the client already has its answer
  2. the rest of the list
  3. who still sees the exception
  4. Exception in ASGI application

basics

~20 s

The client keeps the response it already received. The exception stops the remaining tasks of that request, reaches open yield dependencies and the server error middleware, and ends up as an error in the server log.

solid answer

~40 s

Nothing changes for the client: the status and body were sent before the first task started. In FastAPI 0.143 the exception propagates out of the background loop, so the request's later tasks never run. A yield dependency with the default `scope="request"` is still open and sees it raised at its `yield`. Starlette's server-error middleware calls an installed `Exception` or 500 handler but cannot send its response, then re-raises; an `HTTPException` raised in a task turns into `RuntimeError: Caught handled exception, but response already started.` Uvicorn logs `Exception in ASGI application` with the traceback and closes the connection. Nothing retries the task, so catch and log inside each task, and keep failures of one task from cancelling the others.

code

python · 27 lines
python
from fastapi import BackgroundTasks, FastAPI
from fastapi.testclient import TestClient

app = FastAPI()
ran: list[str] = []


def send_welcome_email(email: str) -> None:
    ran.append("email")
    raise ConnectionError("mail server unreachable")


def write_audit_line(email: str) -> None:
    ran.append("audit")


@app.post("/signup", status_code=201)
def signup(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(send_welcome_email, email)
    background_tasks.add_task(write_audit_line, email)
    return {"email": email}


client = TestClient(app, raise_server_exceptions=False)
response = client.post("/signup", params={"email": "[email protected]"})
print(response.status_code, response.json(), ran)
# 201 {'email': '[email protected]'} ['email']

go deeper

for a junior

Remember that the client already has its response, so a failing background task cannot change it, and that the error shows up only in the server log.

for a middle

Trace the exception: remaining tasks skipped, a default-scope yield dependency sees it, handlers cannot respond, Uvicorn logs it and closes the connection.

for a senior

Design for silent failure: catch and log in each task with context, keep tasks independent, alert on the log line, and notice that 2xx access logs hide these errors.

for a principal

Decide which follow-ups a team accepts losing on failure, and route the ones that must succeed or be retried to a task queue instead.

## Where the exception travels A background task runs inside the request's handling, after the response body has been sent. When it raises, the exception climbs the same call stack an endpoint error would, but every layer it meets finds that **the response has already started**. Tracing it from the inside out: 1. **The background loop.** `BackgroundTasks` awaits its tasks one at a time. The exception leaves the loop, so **every task queued after the failing one is skipped**. 2. **Yield dependencies.** FastAPI 0.143 runs the teardown of a yield dependency with the default `Depends(scope="request")` after the response and its tasks, so such a dependency is still open and the exception is **raised at its `yield`**: an `except` block there runs, and `finally` cleanup runs as usual. A dependency declared with `scope="function"` was torn down before the response and never sees it. 3. **Exception handlers.** FastAPI's handler wrapper looks for a handler for the exception's type. If one exists, it cannot use it, because the response has started: it raises `RuntimeError("Caught handled exception, but response already started.")` instead. This is what an `HTTPException` raised inside a task becomes. 4. **Server error middleware.** Starlette's outermost middleware calls the app's handler for `Exception` or `500`, if one is installed, but **does not send its response**, since one has already gone out. It then re-raises, so the server can log the error. 5. **Uvicorn.** It logs `Exception in ASGI application` with the traceback at error level on the `uvicorn.error` logger. Because the response had started, it closes the connection rather than sending a 500. ## What the client sees The client sees exactly the response it already received, typically a `201` or `200` with a complete body. It cannot learn that the welcome email failed, and an `HTTPException` raised from a task does not reach it. | Layer | What it does with the task's exception | |---|---| | client | nothing: it has the full response | | later tasks of the request | never start | | default-scope yield dependency | sees it at `yield` | | `Exception` / 500 handler | called, response discarded | | Uvicorn | logs `Exception in ASGI application` | ## In tests `fastapi.testclient.TestClient` re-raises server exceptions by default (`raise_server_exceptions=True`), so a test whose background task fails errors out even though the status was `201`. With `raise_server_exceptions=False` the test sees the `201`, and only the side effects reveal that the later tasks were skipped. ## Designing tasks for it There is no retry and nobody waiting for the result, so a background task should own its failure handling: - **Catch inside the task.** Wrap the body in `try` / `except Exception` and call `logger.exception(...)` with enough context to act on: the user ID, the operation, never the email body or credentials. - **Keep tasks independent.** If the audit line must be written even when the email fails, a failure in the email task must not end the list; catching inside each task achieves that. - **Do not raise `HTTPException` in a task.** It has no client to reach, and only produces the `RuntimeError` above. - **Make failure visible.** Count failed tasks in your metrics or alert on the log line; a 2xx access log hides them. - **Re-evaluate the tool.** If a failure must lead to a retry, the job wants a task queue with retries, not an in-process follow-up. A task that owns its failure looks like this: ```python import logging logger = logging.getLogger("signup.tasks") def send_welcome_email(user_id: int, email: str) -> None: try: ... # talk to the mail server except Exception: logger.exception("welcome email failed for user %s", user_id) ``` Nothing escapes, so the next task in the list still runs, and the log line carries the context an operator needs. None of these layers can change the response the client already has; the server log is the only place the failure surfaces unless the task reports it itself.

  • Can a FastAPI exception handler report a background task's failure to the client?
    No. An installed `Exception` or 500 handler is still called, which makes it a place to log, but the response it returns is discarded because the client's response has already been sent. A handler registered for the task's own exception type, `HTTPException` included, makes FastAPI raise `RuntimeError` about the started response instead.
  • How do you keep a failing email task from cancelling the audit task in the same FastAPI request?
    Catch exceptions inside each task and log them with `logger.exception`, so nothing escapes the background loop: the email task then fails on its own and the audit task still runs. Without that, the list stops at the first exception that escapes.

  • A failing background task turns the client's response into a 500
  • FastAPI retries a background task that raised an exception
  • Raising HTTPException in a background task sends that error to the client
  • The other tasks of the request still run after one fails
  • Background task errors are swallowed and never logged

Assumes FastAPI 0.143, where a default-scope yield dependency is torn down after the response and its tasks (teardown after the response was restored in 0.118) and scope="function" (added in 0.121) opts out, so only the former sees a task's exception.