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?
answer
- the executor wraps every execution
- ActionDispatch::Executor middleware
- application.action_dispatch source, handled: false
- rescue_responses errors are skipped
- jobs: executor wrap around execute
basics
~20 sRails 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 sRequests 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 linesclass 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
endgo deeper
Know that Rails reports errors nobody rescued, from both requests and jobs, to the error subscribers without extra code.
Name ActionDispatch::Executor as the reporting point for requests, and explain why rescue_responses classes and rescue_from-handled errors are not reported.
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.
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.