There are about a dozen or so reasons why your Rails app might fail to load locally or on a host like Heroku. Below are a few common traps I often fall into (with solutions).

80% of the time, the problem has to do with the combination of Ruby, Rails, Rubygems, or Bundler I'm using. rbenv and rvm might also be causing havoc, so hopefully, this checklist can help you identify the issue.

rvm vs. rbenv

If you are using Mac OS X, I highly suggest you ditch the default Ruby installation and learn about Ruby Version Manager or Rbenv.

I prefer rbenv, and if you're also familiar with brew, then I suggest reading this article.

Ideally, you'll want to pick Ruby 2.2.2 or 2.3.1 or the version required for your specific Rails project.


There are many different versions of Ruby on Rails, including 5.x.x, 4.x.x, 3.x.x, 2.x.x. To make things even more complicated, different versions of Rails require specific versions of Ruby. Half of the challenge is figuring out which version of Rails you want to use and then finding the right Ruby complimentary.

I prefer to go about things differently. I prefer first to identify which version of both Ruby and Rails I will need to deploy on Heroku, AWS, OpenShift, etc. Then, I will start my project. So the first step is to install the version of Ruby I need using rbenv.

This example will install Rails 4.2.1 into Ruby environment 2.2.1.

RBENV_VERSION=2.2.1 rbenv exec gem install rails --version 4.2.1 --no-document

This example will install Rails 5.0.1 into the Ruby environment 2.2.2.

RBENV_VERSION=2.2.2 rbenv exec gem install rails --version 5.0.1 --no-document

Switching Versions

Now I can switch between different versions of ruby and have it's accompanying rails app.

rbenv versions


Switch to Ruby 2.2.1

rbenv local 2.2.1
rails -v


Switch to Ruby 2.2.2

rbenv local 2.2.2
rails -v




It's always a good idea to also update gem and bundle. These two package managers are so crucial to the underlying Rails system that often, you can fix many problems by first double-checking these two packages.

Check your version of Rubgems and ensure it's 2.6.5 or better.

gem -v

Update Rubygems.

gem update --system


Bundler manages the specific gems within your Gemfile.

Check bundle and ensure it's up-to-date.

 bundle -v

Update bundler.

gem install bundler



Most Ruby on Rails apps requires you to install a database. My preferred method is to use brew package manager to install Mongo, MySQL, or Postgresql.

Read More

More to come

I will continue adding more over time.