Tealeaf Academy Blog

Teaching Ruby on Rails Courses

How to Debug Rails in the Context of Your Application

As a Ruby developer, we may quite often find ourselves in the situation that we need to dive into the source code of a Ruby gem to figure out exactly what’s going on under the hood. While you could go to the gem’s Github repository to check the source code, the ability to be able to step into and debug the library in the context of your app can be very helpful.

Recently, we helped a student on an issue that rake db:reset was not doing what she expected it to do. We had her run rake -T -A and checked the documentation, but somehow things just didn’t work on her machine the way it’s documented. In the end, we asked her to pull the Rails source code locally, stepped into Rails and debug in the context of her environment and had this issue resolved.

Here are the steps you can do to debug Ruby gems locally in the context of your app. We’ll use Rails as an example – Remember, Rails itself is just a Ruby gem!

1. Pull down the gem’s source from Github, for example

git clone git@github.com:rails/rails.git

2. Check out the version of the gem you are using

They are typically tagged as releases. For example, in our case, it’s Rails 4.0.4, therefore,

git checkout tags/v4.0.4

If you want to see how the project is tagged, you can do

git tag -l

3. Open up the Gemfile in your Rails project and point the gem to the local location where you just cloned the code to

gem 'rails', '4.0.4', path: '~/my/local/rails/directory'

4. Run bundle install:

bundle install

Now our project will use Rails from the local repository, therefore, we can drop pry debuggers there to debug any issues. If next time your ruby gems are giving you issues and browsing through the libary’s source code is not enough to figure out, give this method a try!

Note: It has been pointed to me in the comments that Bundler local path is a great way to do this too. You can check it out here: