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 a lot of 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. So half of the challenge is figuring out which version of Rails you want to use and then find the right Ruby complimentary.

I prefer to go about things differently. I find it simpler to first determine which version of both Ruby and Rails I will need to deploy on Heroku, AWS, OpenShift, etc., then start my project. So the first step is into 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 oftentimes, 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 is used to manage 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 require you to install a database. My preferred method it to use brew package manager to install Mongo, MySQL or Postgresql.

Read More

More to come

I will continue adding more over time.