skip to content

In a Rails 8.1 app, how do you pause a request inside a controller action or model method, and what does the generated Gemfile contribute?

level: juniorimportance: must knowfreq 60%

answer

  1. one method call on the line
  2. development and test group
  3. require: "debug/prelude"
  4. prompt in the bin/rails server terminal
  5. the browser waits meanwhile

basics

~20 s

Put debugger, or binding.break, on the line you want to inspect. The generated Gemfile loads the debug gem in development and test with require: "debug/prelude", so the call opens an rdbg prompt in the terminal running the server while the request waits.

solid answer

~40 s

A new Rails 8.1 app has `gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"` in the `:development, :test` group. The prelude only defines `Kernel#debugger` and the `binding.break` and `binding.b` aliases. The debugger itself loads on the first call, so boot does not pay for it. Drop `debugger` into `CartsController#show` or a model method such as `Cart#discount_total`, reload the page, and the terminal running `bin/rails server` shows the source around that line and an `(rdbg)` prompt. The browser's request hangs until you continue. You can read `@cart`, `params` or locals, then continue. Because only development and test require the gem, a `debugger` left in committed code raises `NameError` in production, and the omakase RuboCop config does not flag it.

go deeper

for a junior

Recall that debugger or binding.break pauses the request and that the prompt appears in the terminal running the server, not in the browser.

for a middle

Explain the Gemfile line: the development and test group, the platforms option, and why debug/prelude loads the debugger lazily.

for a senior

Show how you keep breakpoints out of production, knowing the gem is not loaded there and the omakase RuboCop config will not flag them.

for a principal

Decide how the team debugs locally versus in shared environments, and what guardrails keep interactive breakpoints out of deployed code.

## What the generated app sets up `rails new` writes this into the `Gemfile`: ```ruby group :development, :test do # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem gem "debug", platforms: %i[ mri windows ], require: "debug/prelude" end ``` Three details matter: - **The group.** Bundler requires the `:development` and `:test` groups only in those environments (`Bundler.require(*Rails.groups)` in `config/application.rb`). Production never loads the gem. - **`platforms: %i[ mri windows ]`.** The debug gem is built for CRuby, so other Ruby implementations skip it. - **`require: "debug/prelude"`.** Requiring `"debug"` itself would load the debugger and start a session while the app boots. The **prelude** is tiny: it defines `Kernel#debugger` and aliases `Binding#break` and `Binding#b` to it. The real debugger is loaded on the **first call**, so a normal boot pays nothing. ## Setting a breakpoint Say a toy store's cart page shows the wrong discount. You suspect the model, so you stop there: ```ruby class Cart < ApplicationRecord has_many :line_items def discount_total debugger line_items.sum { |item| item.price * item.discount_rate } end end ``` Reload the cart page. Here is what happens: 1. The request runs through the router, the controller and into `Cart#discount_total` on a Puma thread. 2. `debugger` loads the debug gem, opens a session and suspends at that line. 3. The terminal running `bin/rails server` prints the surrounding source, the current frame and an `(rdbg)` prompt. 4. The browser shows its loading indicator, because the response has not been written yet. While the session is suspended, the debug gem also pauses the process's other threads, so other pages wait too. 5. You evaluate Ruby at the prompt, for example `line_items.map(&:discount_rate)` or `self`. When you tell the debugger to continue, the request finishes and the page renders. `binding.break` and `binding.b` do the same thing. The guide uses `debugger` because it reads well in a controller. ## Where the prompt appears | Code path | Where the prompt shows | |---|---| | Controller action or model method during a page load | The terminal running `bin/rails server` | | The same method called from a test | The terminal running `bin/rails test` | | A job run by the default `:async` adapter in development | The server terminal, since jobs run on the server's threads | | The method called from `bin/rails console` | The console session itself | When nobody is watching the terminal, the request simply waits. That is the most common "my page hangs" report from a teammate who left a breakpoint in. ## Choosing where to stop Rails developers usually have three ways to look inside a running request, and each fits a different moment: - **`debugger`** stops *before* something goes wrong, in a terminal, and lets you step forward line by line. It is the tool when you know roughly where the bad value appears. - **`console` from web-console**, called in an action or view, gives you a Ruby console in the browser for the page you are looking at, with no terminal involved. - **The exception page's console** appears *after* something raised, bound to the frame that raised. It is ideal when the code already fails loudly. A wrong discount that raises nothing calls for `debugger` or `console`. A `NoMethodError` on `nil` is usually solved on the exception page. ## Leaving breakpoints behind - **Production.** The gem is not required there, so a `debugger` line raises **`NameError`** (undefined local variable or method `debugger`) when that code runs. One forgotten line turns a working checkout into a 500. - **Linting.** The generated `.rubocop.yml` inherits `rubocop-rails-omakase`, which disables the whole `Lint` department. Nothing flags a stray `debugger` unless you enable a cop for it yourself. - **Habit.** Search the diff for `debugger` and `binding.b` before committing, or add a check to your CI. ## Why not `puts` or the logger? A log line tells you what you thought to print in advance. A breakpoint lets you ask questions you only think of once you see the state: an association that is unexpectedly loaded, a `params` key spelled differently, a discount rate stored as an integer. Logs are better for timing and for production. Breakpoints are better when you can reproduce the bug locally. ## Takeaway The Gemfile line makes `debugger` available in development and test at no boot cost. You put the call on a line, trigger the code path, and use the prompt in whichever terminal runs that code. Delete the line before it ships, because production does not have the method.

  • Why does the generated Gemfile say require: "debug/prelude" instead of letting Bundler require "debug"?
    Requiring `"debug"` loads `debug/session` and starts a debugger session while the app boots, unless `RUBY_DEBUG_LAZY` is set. `debug/prelude` only defines `Kernel#debugger` and the `binding.break` and `binding.b` aliases, which load the real debugger on first use. Boot stays fast and no session exists until you actually stop somewhere.
  • A colleague's `debugger` line reached production. What happens when a customer hits that code?
    Production does not require the `:development, :test` group, so `debugger` is undefined there. Ruby raises `NameError` at that line and the request fails with a 500, or the job fails. Nothing caught it earlier because the omakase RuboCop config disables the `Lint` department. A search for `debugger` in the diff, or a CI check, is the safeguard.

  • You must add require "debug" at the top of the controller before calling debugger.
  • The debugger prompt opens in the browser tab that made the request.
  • require: "debug/prelude" starts a debugger session every time the app boots.
  • A leftover debugger call is a no-op in production, so it is harmless.
  • The generated RuboCop config fails the build on a stray debugger call.
  • debugger only works in controllers, not in models or jobs.