Debugging Ruby on Rails server in VS Code

4 min readOct 18, 2020

Using VS Code Debugger for Ruby on Rails server

I recently got assigned to new tasks on a Rails project. Project is powering an organization platform so code must be large and if the codebase is large so does its difficulty in understanding any of the features at first glance. Today I found how to use VS code debugger with Rails server so just sharing up…

First, to enable debugging for Ruby, install Ruby extension

Next, we need to install gems that actually do the debugging

# for Ruby 2.x
$ gem install ruby-debug-ide
$ gem install debase

Once it's done, we need to add configuration in our launch.json.

So go to the debug tab on the left in VS Code. Create a launch.json file for Ruby if don’t already have it else click on the gear icon at the top to open it. Then click ‘Add configuration’ and select ‘Ruby: Rails server’ option. It will add config something like this:

{
    "name": "Rails server",
    "type": "Ruby",
    "request": "launch",
    "program": "${workspaceRoot}/bin/rails",
    "args": [
        "server"
    ]
}

If you want to use port other than default port (3000) for the rails server then you can specify that in arguments like this

"args": [
    "server",
    "-p",
    "3100"
]

Now, after adding configuration, if you click ‘Run’ with the ‘Rails server’ option selected in the drop-down it will start up in debug mode. Add some breakpoints and enjoy debugging!

What? Got some error? Refer to some I also got and workarounds I found…

Troubleshooting

1. Everything was running great with the newly created Rails project but not with the existing project I am assigned to in my task. I was getting the following error in the debug console:

Debugger terminal error: Process failed: spawn rdebug-ide ENOENT

janniks answer on StackOverflow suggested my environment variables (env) are most likely not set. I ran the following shell command to generate your env:

$ printf "\n\"env\": {\n  \"PATH\": \"$PATH\",\n  \"GEM_HOME\": \"$GEM_HOME\",\n  \"GEM_PATH\": \"$GEM_PATH\",\n  \"RUBY_VERSION\": \"$RUBY_VERSION\"\n}\n\n"

and add it in env section in launch configuration like:

{
    "name": "Rails server",
    "type": "Ruby",
    "request": "launch",
    "program": "${workspaceRoot}/bin/rails",
    "env": {
        "PATH": "/Users/rahul/.rvm/gems/ruby-2.5.3@platform-api/bin:/Users/rahul/.rvm/gems/ruby-2.5.3@global/bin:/Users/rahul/.rvm/rubies/ruby-2.5.3/bin:/Users/rahul/.rvm/bin",
        "GEM_HOME": "/Users/rahul/.rvm/gems/ruby-2.5.3@platform-api",
        "GEM_PATH": "/Users/rahul/.rvm/gems/ruby-2.5.3@platform-api:/Users/rahul/.rvm/gems/ruby-2.5.3@global",
        "RUBY_VERSION": "ruby-2.5.3"
    },
    "args": [
        "server"
    ]
}

Thanks to janniks and error was resolved.

2. Previous solution resolved the corresponding error. Rails server was running and pausing the server thread on breakpoints but VS code was not highlighting the code line and means not listening to the rdebug-ide. I found no error on the debug console. I tried adding pathToRDebugIDE as suggested by andyv in step 3 of his post. But that didn’t work as well.

Then after checking Ruby extension’s page on VS code, I reached out Debug Configuration docs and found how to run debugger from command line:

$ rdebug-ide --host 0.0.0.0 --port 1234 --dispatcher-port 1234 -- bin/rails s

This ran up the Rails server in debug mode but now how to attach to it? No worries! Same doc provided hint/configuration for launch.json. In launch.json, I added the configuration named ‘Ruby: Listen for rdebug-ide’ and VS code generated this for me:

{
    "name": "Listen for rdebug-ide",
    "type": "Ruby",
    "request": "attach",
    "remoteHost": "127.0.0.1",
    "remotePort": "1234",
    "remoteWorkspaceRoot": "${workspaceRoot}"
}

Next, the server was already running in debug mode, so run the script just created and finally get it worked!

3. There was one more issue I faced while starting the server in debug mode. Upon executing rdebug-ide - host 0.0.0.0 - port 1234 - dispatcher-port 1234 - bin/rails s and attaching listener to it, the server tried to start but workers were terminating like:

Rails 6.0.2.1 application starting in development 
=> Run `rails server --help` for more startup options
/Users/cronycle/.rvm/gems/ruby-2.5.3@cronycle-api/gems/zeitwerk-2.2.2/lib/zeitwerk/loader.rb:532: warning: constant ::Data is deprecated
[51744] Puma starting in cluster mode...
[51744] * Version 3.12.2 (ruby 2.5.3-p105), codename: Llamas in Pajamas
[51744] * Min threads: 1, max threads: 16
[51744] * Environment: development
[51744] * Process workers: 4
[51744] * Preloading application
[51744] * Listening on tcp://localhost:3000
[51744] Use Ctrl-C to stop
[51744] ! Terminating timed out worker: 51753
[51744] ! Terminating timed out worker: 51754
[51744] ! Terminating timed out worker: 51755
[51744] ! Terminating timed out worker: 51756

So, somewhere deep down in a GitHub issue, I found a solution in bradleygolden’s comment. In puma.rb, I updated the env variables as PUMA_WORKERS=0 and RAILS_MAX_THREADS=1 and it worked for me as well! Since I am working locally so multithreading doesn’t matter to me.

I didn’t use bundler in my configurations though I found few configurations for that while resolving my errors. If anyone wants to refer to that, can check at this link.

References:

Debugging Ruby on Rails server in VS Code

Troubleshooting

Written by Rahul Arora