In Rails 8.1 development, what does the exception page show when an action raises, and how do you use it to find the bug?
answer
- ActionDispatch::DebugExceptions
- Extracted source around the line
- Application, Framework and Full Trace
- parameters, session and env dumps
- web-console at the bottom; Copy as text
basics
~20 sActionDispatch::DebugExceptions renders the exception class, controller and action, message, source around the failing line, the application trace and the request's parameters and headers. web-console adds a live console in the failing frame. Rails 8.1 adds a Copy as text button.
solid answer
~40 sIn development, `ActionDispatch::DebugExceptions` catches the exception and renders a diagnostic page. The heading names the exception class with the controller and action, for example `NoMethodError in CartsController#show`. Below it come the message with any did-you-mean suggestions, **Extracted source** around the failing line, and switchable **Application, Framework and Full Trace** views. Then **Exception Causes**, the request's **Parameters**, toggles for the session and env dumps, and the response headers. Some errors carry action buttons; a pending migration shows **Run pending migrations**. With web-console installed, a console at the bottom runs in the frame that raised, and clicking another trace line switches to that frame. Rails 8.1 adds **Copy as text**, which copies the report for an issue or a chat. You start at the first application-trace line, then use the console to inspect values there.
go deeper
Recall what the page shows, from heading and message to extracted source, the application trace and parameters, and start reading at the first application frame.
Explain that DebugExceptions renders the page, how actionable errors and XHR or API responses differ, and how web-console binds to the failing frame.
Use the trace, causes, parameters and frame-switching console to confirm a root cause before changing code, and know what never reaches this page.
Decide how much diagnostic detail each environment may expose and how developers get equivalent insight where the page is off.
## Who renders the page When an action raises and nothing rescues it, the exception travels back up the middleware stack. **`ActionDispatch::DebugExceptions`** catches it, logs it, and, when the request is allowed to see details, renders a diagnostic page. The generated `development.rb` allows that for every request, and `rescue_from`, public error pages and production behaviour are a separate topic. Before rendering, `DebugExceptions` calls its registered **interceptors**. web-console registers one, which is how its console gets hold of the exception. The response format follows the request: - a normal browser request gets the HTML page; - an XHR request gets the same report as plain text; - in an API-only app, a non-HTML request gets a structured body with `status`, `error`, `exception` and `traces`, as JSON for a JSON request. ## What is on the page Consider a toy store whose cart page raises `NoMethodError` while computing a discount: 1. **Heading.** `NoMethodError in CartsController#show`, built from the exception class and the routing params. 2. **Message and suggestions.** `undefined method 'discount_rate' for nil`, plus did-you-mean hints when Ruby offers them. 3. **Action buttons.** Errors that include `ActiveSupport::ActionableError` show buttons. `ActiveRecord::PendingMigrationError`, raised on page load because development sets `config.active_record.migration_error = :page_load`, shows **Run pending migrations**. 4. **Extracted source.** The lines around the failing line in the file that raised, with the line highlighted. 5. **`Rails.root` and the traces.** Three switchable views: **Application Trace** (your code only), **Framework Trace** (Rails and gems) and **Full Trace**. The application trace is shown by default when it is not empty. 6. **Exception Causes.** When the exception wraps another, such as an `ActionView::Template::Error` wrapping the real error, each cause gets its own source and trace. 7. **Request and response.** The **Parameters** of the request, *Toggle session dump*, *Toggle env dump*, and the response headers. 8. **Copy as text.** **New in Rails 8.1**: a button that copies the plain-text version of the report, handy for an issue or a message to a colleague. Routing errors get a variant: `No route matches [GET] "/carts/abc/discount"` followed by a searchable table of the app's routes, in priority order. ## The console at the bottom The generated Gemfile puts **web-console** in the `:development` group. On the exception page it renders a Ruby console **in the binding of the frame that raised**, with that frame's locals, `self` and instance variables. Clicking another line in the trace switches the console to that frame. For the toy-store bug you can evaluate `line_items.map(&:product)` at the failing frame, see which item has no product, and know whether the bug is in the data or the code, without restarting anything. ## A routine for reading it 1. Read the heading and the message. They usually name the wrong object. 2. Look at the **first Application Trace line**. Framework frames are rarely where the bug is. 3. Read the extracted source and the **Parameters** together. A `nil` often comes from a param that was missing or named differently. 4. Use the console to confirm: evaluate the expression that failed, piece by piece. 5. Fix, then reload. In development, code reloading means no restart. ## The page versus a breakpoint The exception page is a snapshot taken after the failure. You get the state at the moment of the raise, and the bindings of every frame on the way there. You cannot step forward from it, and you cannot see values that were overwritten before the raise. When the failing value was produced several calls earlier, put a `debugger` call where it is computed and reload. When the failure is local, as most `nil` errors are, the page and its console are enough. ## Limits - The page appears only when the request is allowed detailed exceptions, which the generated development configuration grants and production does not. - The console works only for HTML responses and only for requests from permitted IP addresses, by default localhost. - An exception in a job running in the background never reaches this page, because no browser request is waiting for it. Look in the logs or the job dashboard instead. ## Takeaway The development exception page is a report built from the exception, its trace and the request. Read it top down, start at the first application frame, and use web-console's frame-aware console to test your theory in place. In Rails 8.1, Copy as text gives you the whole report as plain text.
- The exception page shows Run pending migrations. Where does that button come from?`ActiveRecord::PendingMigrationError` includes `ActiveSupport::ActionableError` and declares a `Run pending migrations` action. Development's `config.active_record.migration_error = :page_load` raises it on the next request after a new migration appears, and the page renders a button for each declared action. `ActionDispatch::ActionableExceptions` handles the button's POST, runs the migrations and redirects back.
- A Stimulus controller calls an action through @rails/request.js and the action raises. Why does the network tab show text instead of the HTML exception page?request.js sends `X-Requested-With: XMLHttpRequest`, so `request.xhr?` is true, and `DebugExceptions` renders the plain-text version of the report for XHR requests. The content is the same: exception, message and traces. A plain `fetch` without that header gets the HTML page. Either way, `log/development.log` also has the exception and backtrace.
- The development exception page is produced by web-console; without it there is no page.
- The Full Trace is shown first because the bug is usually inside Rails.
- The web-console on the exception page runs in a fresh console, not in the failing frame.
- The exception page also appears for errors raised inside background jobs.
- Copy as text has been on the Rails exception page since Rails 7.0.
- Run pending migrations is a web-console feature that runs any Ruby command.
Assumes Rails 8.1 with web-console 4.3; the Copy as text button on the exception page is new in Rails 8.1.0.