Debug a Rails Request in RubyMine: Conditional Breakpoints and Variable Inspection

Desired Outcome

Suspend a Rails controller action at a specific line only when a condition is true, inspect the call stack and variables, step through the method, and resume without restarting the server.

Prerequisites

• RubyMine 2023.3 or later with the Ruby plugin enabled.
• A Rails project using Ruby 3.1+ with the debug gem in the Gemfile, or an older Ruby with byebug and debase.
• Bundler has installed gems for the Ruby SDK selected in Settings → Languages & Frameworks → Ruby SDK and Gems.
• Port 12345 is free on localhost for the debugger connection.

Verify the Debugger Backend

RubyMine loads the debugger backend from the Bundler environment tied to the project SDK. Confirm it before creating a run configuration.

1. Open Settings → Build, Execution, Deployment → Debugger → Ruby.
2. Check that Debugger backend lists debug for Ruby 3.1+, or byebug/debase for older runtimes.
3. If it shows No debugger found, run bundle install in the RubyMine terminal and restart the IDE.

# Run in RubyMine's built-in terminal
bundle list | grep -E 'debug|byebug|debase'
# Expected: debug (>= 1.7) on Ruby 3.1+, or byebug/debase on older runtimes

If the gem is absent, add it to the development group in Gemfile and run bundle install again.

Create a Rails Debug Configuration

1. Open the run configuration dropdown in the top toolbar and choose Edit Configurations…
2. Click +, select Rails, and name it Rails Debug.
3. Set Server to Puma, Port to 3000, and Environment to development.
4. Leave Run in debug mode enabled.
5. Apply the configuration.

Set a Conditional Breakpoint

Open the controller file. Click the gutter next to an executable line to create a line breakpoint. Right-click the red dot and choose Condition. Enter a Ruby expression that must be true for suspension, such as params[:id] == '42'. The dot remains red but only triggers when the condition matches.

To log a value without suspending, right-click the breakpoint and choose Log expression, then enter @user.inspect or another expression.

Start Debugging and Hit the Breakpoint

1. Select the Rails Debug configuration.
2. Click Debug (Shift+F9). Wait for the debugger to report it is listening on the configured port.
3. Use a browser or curl http://localhost:3000/users/42 to request the route.
4. When the condition is true, execution suspends. The Frames pane shows the call stack, and the Variables pane lists local, instance, and class variables for the selected frame.

Inspect and Step Through

• Inline values appear beside variables in the editor when enabled under Settings → Build, Execution, Deployment → Debugger → Data Views → Show values inline.
• Watches: add arbitrary expressions such as session[:user_id] to the Watches tab.
• Step actions:
  • F8 Step Over — advance to the next line in the current frame.
  • F7 Step Into — enter the called method.
  • Shift+F8 Step Out — return to the caller.
  • Alt+Shift+F7 Force Step Into — enter code in gems or the standard library.
  • Drop Frame — right-click a frame in the Frames pane to rewind to its caller without re-executing the request.
• Evaluate Expression (Alt+F8) runs Ruby code in the current binding while suspended.

Expected Checks

1. The Frames pane contains the controller action and at least one caller frame.
2. The Variables pane shows params, @user, or other expected objects with current values.
3. Pressing F8 moves the execution pointer to the next executable line.
4. Pressing F9 resumes the request and returns an HTTP response to the client.

Common Failure Modes and Recovery

Symptom	Likely Cause	Recovery
Breakpoint never suspends (hollow red dot)	Debugger gem missing or version mismatch with the Ruby SDK	Run bundle list | grep debug in the RubyMine terminal. Install the missing gem and restart RubyMine.
Request hangs or times out	Debugger suspension blocks the Puma thread; reverse proxies or health checks exceed their timeout	Increase the proxy read timeout or temporarily disable health checks. Keep debugging sessions brief.
Cannot connect to debugged process	Port 12345 is occupied or localhost is blocked	Change the debugger port under Settings → Build, Execution, Deployment → Debugger → Ruby and confirm localhost resolves to 127.0.0.1.
Variables read as unavailable	Ruby JIT is enabled and interferes with frame introspection	Disable JIT for the debug session by clearing --jit from RUBYOPT in the run configuration environment variables.
Sidekiq job is not debugged	A Rails server configuration only attaches to the web process, not background workers	Create a separate Ruby run configuration for bundle exec sidekiq, enable debug mode, and use a distinct debugger port.

Limitations

• Suspending the debugger pauses all threads in the process, so other concurrent requests stall in a multi-threaded server.
• Attaching the debugger can slow a large Rails application; avoid debugging under production-like load.
• Breakpoints are stored in the .idea workspace and are user-local unless you commit workspace files, which is not recommended.
• Remote or Docker debugging requires port forwarding and matching debugger gem versions on both ends; this guide covers local debugging only.

Quick Verification Checklist

1. bundle list | grep debug returns a debugger backend gem.
2. Settings → Debugger → Ruby lists the same backend.
3. A conditional breakpoint in UsersController#show suspends only when the condition matches.
4. The Frames pane shows show and its caller.
5. The Variables pane displays params and controller instance variables.
6. F8 steps to the next line; F9 resumes and the browser receives a response.

When all six checks pass, RubyMine is correctly configured to debug Rails requests.