skip to content

In a Rails 8.1 app with no rescue code of your own, how does an exception raised in a controller action or an Active Job reach Rails.error subscribers?

level: seniorimportance: should knowfreq 30%

answer

  1. the executor wraps every execution
  2. ActionDispatch::Executor middleware
  3. application.action_dispatch source, handled: false
  4. rescue_responses errors are skipped
  5. jobs: executor wrap around execute

basics

~20 s

Rails runs every request and job inside its executor. ActionDispatch::Executor reports an escaping request error with handled: false, and the executor around each job reports whatever perform lets escape. rescue_responses classes, such as 404s, are skipped.

solid answer

~40 s

Requests pass through `ActionDispatch::Executor`, near the top of the middleware stack. In production, when an action raises, `ShowExceptions` renders the error page and flags whether to report, skipping classes in `rescue_responses` such as `ActiveRecord::RecordNotFound`; the executor then reports the error with `handled: false` and source `"application.action_dispatch"`. If the error propagates instead, the executor reports it and re-raises. In development the debug page renders it lower down, so nothing is reported. Jobs: Active Job runs each execution inside the app's executor, which reports whatever escapes `perform` and is not handled by `rescue_from`, `retry_on` or `discard_on`, with `handled: false`, then re-raises so the backend records the failure. `bin/rails runner` is wrapped the same way. Rails 8.1 reports non-`StandardError` exceptions here too.

code

ruby · 9 lines
ruby
class GeocodeListingJob < ApplicationJob
  retry_on Net::OpenTimeout, attempts: 3          # retried unreported; the 3rd failure escapes
  discard_on ActiveJob::DeserializationError       # dropped, not reported

  def perform(listing)
    coordinates = GeocodingClient.lookup(listing.address)
    listing.update!(coordinates: coordinates)       # RecordInvalid escapes perform:
  end                                              # reported with handled: false, then re-raised
end

go deeper

for a junior

Know that Rails reports errors nobody rescued, from both requests and jobs, to the error subscribers without extra code.

for a middle

Name ActionDispatch::Executor as the reporting point for requests, and explain why rescue_responses classes and rescue_from-handled errors are not reported.

for a senior

Diagnose missing reports: no subscriber, development's debug page, rescue_from, retry_on without report:, or source filtering; and rely on the reported-once marking.

for a principal

Decide which handled failures deserve explicit reports, and make sure background work outside the executor is wrapped so nothing fails silently.

## The executor is the hook Rails runs each unit of work, an HTTP request, an Active Job execution, a `bin/rails runner` script, inside the **application executor** (`Rails.application.executor`, an `ActiveSupport::ExecutionWrapper`). The executor resets per-execution state (the error context, `Current` attributes, database connections) and, since the error reporter exists, it also **reports exceptions that escape the work**. That is why a tracker subscriber sees unhandled errors without any Rack middleware or monkey-patching of its own. ## Requests The default middleware stack includes, from outer to inner: 1. **`ActionDispatch::Executor`**: opens the execution and is responsible for reporting. 2. **`ActionDispatch::ShowExceptions`**: turns an exception into an error response. 3. **`ActionDispatch::DebugExceptions`**: renders the detailed developer page. 4. ... your routes and controller. What happens to an exception raised in an action: - **Rescued by the controller** (`rescue_from`): it never leaves the controller, so nothing reports it. Call `Rails.error.report` inside the handler if you want it tracked. - **Production** (`consider_all_requests_local` false): `DebugExceptions` re-raises; `ShowExceptions` stores the exception in the request env, sets a flag that is true **unless the class is in `rescue_responses`**, and renders the public error page. On the way out, `ActionDispatch::Executor` sees the flag and reports with `handled: false`, `source: "application.action_dispatch"`. - **Propagating past `ShowExceptions`** (for example in tests, where `show_exceptions` is `:rescuable`): the executor's own `rescue Exception` reports it and re-raises. - **Development**: `DebugExceptions` renders the detailed page and returns a normal response, so the exception never reaches the executor and **is not reported**. Do not test a subscriber by clicking through the dev error page. `rescue_responses` maps exception classes to statuses: `ActionController::RoutingError` and `ActiveRecord::RecordNotFound` to 404, `ActiveRecord::RecordInvalid` to 422 and so on. Those are client-side outcomes, not bugs, so they are left out of the tracker. ## Jobs Active Job registers an `around` callback on job execution that runs the job inside `app.reloader.wrap`, which opens the executor unless one is already open: | What happens in `perform` | Reaches the reporter? | |---|---| | completes | no | | raises, handled by `rescue_from` | no, the job's handler swallowed it | | raises, matched by `discard_on`, or by `retry_on` with attempts left | only if that macro is given `report: true` | | raises, `retry_on` out of attempts and given no block | yes: the error is re-raised and escapes | | raises, nothing handles it | yes: `handled: false`, then re-raised | The re-raise matters: the queue backend still sees the failure and records it. Which `source` string the report carries depends on who opened the executor: Rails' default wrapper uses `"application.active_support"`, while Solid Queue opens it itself with `"application.solid_queue"`. ## Reported once After a report, Rails marks the exception and every exception in its `cause` chain. If your code already called `Rails.error.record` (or `report`) and re-raised, the executor's report of the same object is skipped: the tracker shows one event, with your context. ## What Rails 8.1 changed Rails 8.1 changed execution wrapping to report **all** exceptions, including ones outside `StandardError` such as `SystemStackError` or `NoMemoryError`, so the most serious failures in jobs and runner scripts also reach subscribers. ## Work outside the executor The automatic reporting only covers code running inside an execution. `bin/rails runner` scripts are wrapped (their source is `"application.runner.railties"`), but a `Thread.new` you start yourself, or a long-lived loop in a custom process, is not. Wrap that work in `Rails.application.executor.wrap { ... }`: it gives the code a fresh execution context and reports an escaping exception with `handled: false` before re-raising it. ## Checklist when a tracker misses errors - Is a subscriber actually registered (`rails new` adds none)? - Was the error a `rescue_responses` class, rescued by `rescue_from`, or retried by `retry_on`? - Are you looking at development, where the debug page renders it unreported? - Is the subscriber filtering on `source` or `severity` too aggressively?

  • Why does your subscriber receive nothing when you trigger an error in development and see the detailed error page?
    With `consider_all_requests_local` true, `ActionDispatch::DebugExceptions` renders the page and returns a response instead of re-raising. The exception never reaches `ActionDispatch::Executor`, which is where request errors are reported. Test the subscriber from a test or with `Rails.error.report` in a console.
  • A controller has rescue_from GeocodingClient::Error that renders a fallback map. Is the error reported?
    Not automatically. `rescue_from` handles it inside the controller, so no exception reaches the executor. If the tracker should know, call `Rails.error.report(exception)` inside the handler; it defaults to `handled: true` and `severity: :warning`, which matches what happened.

  • Every 404 from ActiveRecord::RecordNotFound shows up in the tracker automatically.
  • A tracker needs its own Rack middleware to see unhandled request errors.
  • Errors handled by rescue_from are still reported by the executor.
  • The development error page reports the exception to subscribers before rendering.
  • A job's unhandled error is reported and then swallowed, so the backend sees success.

Assumes Rails 8.1, whose execution wrapping reports every exception including non-StandardError ones such as SystemStackError; earlier wrapping reported StandardError only.