skip to content

When bin/dev runs a Rails app through foreman, why is a debugger prompt unusable, and how do you attach to the stopped request?

level: middleimportance: should knowfreq 30%

answer

  1. only when Procfile.dev exists
  2. foreman pipes and prefixes output
  3. RUBY_DEBUG_OPEN=true
  4. UNIX domain socket
  5. rdbg --attach from another terminal

basics

~20 s

Foreman pipes each process's output through itself and prints it line by line, so the web process's interactive prompt does not work reliably. Start the server with RUBY_DEBUG_OPEN=true, so the debugger opens a socket, and attach from another terminal with rdbg --attach.

solid answer

~40 s

In Rails 8.1 an import-map app's `bin/dev` just execs `bin/rails server`, so `debugger` prompts in that terminal. Once a CSS or JS bundling gem installs `Procfile.dev`, `bin/dev` runs `foreman start -f Procfile.dev`. Foreman starts each process with its output piped back to foreman, which prefixes and prints it line by line. The `(rdbg)` prompt from the web process is not usable there. The fix is remote debugging. With `RUBY_DEBUG_OPEN=true` in the web process's environment, a `debugger` call opens a UNIX domain socket and waits, and you run `rdbg --attach` in a second terminal to get the prompt. tailwindcss-rails' `bin/dev` exports it, as do the Procfile.dev files jsbundling-rails and cssbundling-rails write. dartsass-rails' does not, so you add it there.

go deeper

for a junior

Recall that under foreman the web process's prompt cannot be used, and that attaching from a second terminal with rdbg --attach is the fix.

for a middle

Explain why foreman's piped output breaks the prompt, which bin/dev variants use foreman, and how RUBY_DEBUG_OPEN switches the debugger to a socket.

for a senior

Set up a team's bin/dev so debugging works out of the box, without exposing a debugger port on the network.

for a principal

Weigh one combined dev process against separate terminals or editor-attached debugging for the team's onboarding and daily workflow.

## Two kinds of bin/dev What `bin/dev` does depends on how the app builds its assets: | App | `bin/dev` does | Debugger prompt | |---|---|---| | Import maps and Propshaft only (Rails 8.1 default) | `exec "./bin/rails", "server", *ARGV` | Works in that terminal | | tailwindcss-rails, jsbundling-rails, cssbundling-rails or dartsass-rails installed | `exec foreman start -f Procfile.dev ...` | Not usable in the foreman terminal | The installers of those gems replace `bin/dev` with a shell script that installs foreman if needed and starts every line of `Procfile.dev` (most also default `PORT` to 3000), for example `web: bin/rails server` and `css: bin/rails tailwindcss:watch`. ## Why the prompt breaks under foreman Foreman starts each Procfile line as a child process whose standard output and error go into a **pipe** that foreman reads. It reads that pipe a line at a time and reprints each line with a `web.1 |` prefix, mixed with the CSS watcher's output. So the web process's output is not a terminal. The debugger's prompt has no trailing newline and may not appear until more output follows, and every child shares the same keyboard input. An interactive session does not work reliably there. The request sits suspended, and the browser spins. ## Remote debugging: the fix The debug gem can serve its console over a socket instead of the terminal. The switch is the environment variable **`RUBY_DEBUG_OPEN`**: 1. Make sure the web process starts with `RUBY_DEBUG_OPEN=true`. 2. Hit the `debugger` line. The gem opens a **UNIX domain socket** and prints a line saying the debugger can attach via that socket. The request is suspended, waiting for a client. 3. In a second terminal, in the app directory, run `rdbg --attach` (short form `rdbg -A`). With a single socket in the default directory, it connects automatically. 4. You get the usual prompt, attached to the suspended request. Quitting the remote console detaches it and leaves the server running. The generated setups already do step 1 in different ways: - **tailwindcss-rails** writes a `bin/dev` that exports `RUBY_DEBUG_OPEN="true"` and `RUBY_DEBUG_LAZY="true"` before starting foreman, with a comment saying the debugger is allowed to take remote connections but is not loaded until `debugger` is called. - **jsbundling-rails and cssbundling-rails** put it on the web line of `Procfile.dev`: `web: env RUBY_DEBUG_OPEN=true bin/rails server`. - **dartsass-rails** writes `web: bin/rails server -p 3000` with no variable, so you add `env RUBY_DEBUG_OPEN=true` yourself. `RUBY_DEBUG_LAZY` matters when something requires plain `"debug"`, typically an older Gemfile. It makes that require behave like `debug/prelude`, so nothing loads until a breakpoint is hit. A new app's Gemfile already uses the prelude. ## Checking an app's setup When a colleague says "debugger hangs under bin/dev", walk through it in order: 1. **Read `bin/dev`.** If it execs `bin/rails server`, the prompt should work in that terminal and foreman is not the problem. 2. **Read `Procfile.dev`.** Check whether the `web:` line, or `bin/dev` itself, sets `RUBY_DEBUG_OPEN=true`. 3. **Trigger the breakpoint.** Look in foreman's output for the debug gem's line saying it can attach via a UNIX domain socket. 4. **Attach.** Run `rdbg --attach` in a second terminal from the app directory. 5. **Finish.** Continue from the remote console. The request completes and the page renders. ## Alternatives - **Separate terminals.** Run `bin/rails server` in one terminal and the watcher, for example `bin/rails tailwindcss:watch`, in another. The server terminal is then interactive again and `debugger` prompts there. - **An editor client.** The same socket serves the debug gem's editor integrations, which attach instead of `rdbg`. ## Safety notes - The UNIX domain socket lives on your machine, in a per-user directory the debug gem checks before using. A **TCP** port (`RUBY_DEBUG_PORT`) binds to `127.0.0.1` by default. Pointing `RUBY_DEBUG_HOST` at a wider address exposes a code-execution console on the network, and the debug gem warns that its messages are not encrypted. - Remote mode is a development tool. Nothing here should be set in production's environment. ## Takeaway `debugger` itself does not change. What changes is where its console lives. Under foreman the terminal belongs to foreman, so you let the debug gem open a socket with `RUBY_DEBUG_OPEN` and attach with `rdbg --attach` from a terminal of your own.

  • Your app's bin/dev runs foreman, but its Procfile.dev web line is plain `web: bin/rails server -p 3000`. What do you change to debug a request?
    Add the variable to the web line, `web: env RUBY_DEBUG_OPEN=true bin/rails server -p 3000`, or export it in `bin/dev`. Restart `bin/dev`, trigger the `debugger` line, then run `rdbg --attach` in another terminal. Without the variable, the debug gem tries to use the foreman-piped terminal, and you cannot interact with the prompt.
  • What does RUBY_DEBUG_LAZY add next to RUBY_DEBUG_OPEN in tailwindcss-rails' bin/dev?
    It makes a plain `require "debug"` load only the prelude instead of starting a session at boot. A new Rails 8.1 Gemfile already requires `debug/prelude`, so for such apps it changes nothing. It matters for older Gemfiles that require `"debug"` directly, which would otherwise open the remote socket as soon as the server boots.

Foreman is a switchboard operator relaying several callers' messages to you one line at a time. You can hear each caller, but you cannot hold a private back-and-forth with one. Remote debugging gives that caller a direct line you dial yourself.

  • Every Rails 8.1 app's bin/dev runs foreman, even with import maps only.
  • Foreman forwards your keystrokes to whichever process printed last.
  • RUBY_DEBUG_OPEN makes the debugger skip breakpoints so foreman keeps running.
  • You must restart the server with rdbg -c to attach to a request.
  • Binding the debugger to 0.0.0.0 is safe because its traffic is encrypted.
  • With debug/prelude, RUBY_DEBUG_OPEN opens the debugger socket as soon as the server boots.