In Django, what happens when one of several transaction.on_commit() callbacks raises an exception, and what does robust=True change?

## Where callbacks run `transaction.on_commit()` callbacks run **after** the outermost `atomic` block commits, inside that block's exit, in the thread that ran the block. The commit has happened by then; a callback cannot make the transaction fail. What a failing callback can do is disrupt what happens *next*. ## Default behaviour: `robust=False` Suppose an order registers three callbacks: send the receipt, enqueue a warehouse task, refresh a cache entry. 1. The order commits. 2. The receipt callback raises (the mail server refused the connection). 3. The exception propagates out of the `atomic` block's exit — the `with` statement raises, or the decorated function raises to its caller. 4. The warehouse and cache callbacks, registered later in the same transaction, are **never called**; the pending list was already taken off the connection. Consequences in a view: the user sees an error page even though the order exists, and a retry by the user may place a second order. The docs describe this as the same behaviour as running the functions sequentially yourself. ## `robust=True` Django 4.2 added the `robust` argument: ```python transaction.on_commit(partial(send_receipt, order.pk), robust=True) transaction.on_commit(partial(warehouse_task.enqueue, order_id=order.pk)) ``` For a robust callback, Django catches any exception derived from `Exception`, logs it with a traceback to the **`django.db.backends.base`** logger ("Error calling … in on_commit() …"), and carries on with the next callback. It applies per callback, so you choose it for each registration. | | `robust=False` (default) | `robust=True` | |---|---|---| | Transaction | Already committed | Already committed | | Exception | Propagates from the block's exit | Caught and logged | | Later callbacks | Not run | Run | | Caller notices | Yes, as an exception | Only via logs | Outside a transaction, where `on_commit()` runs the callable immediately, `robust=True` likewise logs instead of raising. ## Choosing per callback - **Robust**: independent, best-effort effects — a receipt email, a cache refresh, an analytics ping. One failing should not block the others, and the caller already succeeded. - **Not robust**: a step whose failure the caller must act on, or a callback that later callbacks depend on. - **Neither is a retry mechanism**: a robust callback's failure is only a log line. Monitor that logger, or move critical work to a persisted outbox. ## Testing the behaviour `TestCase.captureOnCommitCallbacks(execute=True)` runs captured callbacks when its context exits, and honours `robust`: a robust callback's exception is logged there too, while a non-robust one raises out of the context manager. That lets a test assert both that the view succeeded and that a failing receipt did not stop the warehouse task. ## Diagnosing it in production - Symptom: 500 responses whose tracebacks start in a mail or queue client but whose orders exist in the database. - Symptom: some orders have receipts but no warehouse task — the tasks registered after a failing callback. - Fix: make independent callbacks robust, order dependent ones deliberately, and alert on the `django.db.backends.base` logger. ## Why robust is not the default Making every callback robust would hide failures: the code after the block would carry on as if the side effect happened, and the only evidence would be a log line. Django keeps the default equivalent to calling the functions yourself in sequence, so an unexpected error is loud. `robust=True` is an explicit statement that this particular effect is best-effort and independent of the rest — a decision worth making callback by callback rather than project-wide.