Rails troubleshooting

WARNING Ruby on Rails is considered an advanced topic and is not recommended for anyone new to webhosting or programming. To familiarize or update your Rails knowledge I recommend viewing the Ruby On Rails web site

General Troubleshooting Techniques
There are a number of things that can go wrong when attempting to get your Rails application working. Most of these problems are related to gems not loading properly. Here are some tips on how to determine what's going on with your application if it isn't loading properly.

Use the Console
Rails comes with a very handy tool named the console. You can fire this up by logging into your server via SSH, cd'ing to your app's root directory and running this command:

ruby script/console production

For an application that's setup properly, it should load like this:

$ ruby script/console production Loading production environment (Rails 2.3.5) >>

The ">>" is a prompt. At that point you could execute any arbitrary Ruby code you want to see it's output. Essentially, you have a fully running copy of your application that's connected to your database. The useful thing about this technique is that when it doesn't work all of the errors it encounters get dumped out right there. For instance, here's a very common error to see:

Missing the Rails 2.3.5 gem. Please `gem install -v=2.3.5 rails`, update your RAILS_GEM_VERSION setting in config/environment.rb for the Rails version you do have installed, or comment out RAILS_GEM_VERSION to use the latest version installed.

Generally, this is caused because your application was created using the version of Rails specified in the error message and that version of Rails isn't installed. One thing that's important to note is that Passenger loads your application without your user environment, so if you have a custom gem installation involving a custom GEM_HOME and GEM_PATH in your .bash_profile, then none of the gems you installed at that location will show up for Passenger. Unfortunately, this can create a case where loading the console doesn't reveal any issues because it find the gems due to having loaded your user environment, but Passenger does get errors. To get around this, comment out the custom GEM_HOME and GEM_PATH lines in your .bash_profile, logout and log back into your server. At that point you'll see what Passenger sees for the most part and if you're having trouble you'll likely see errors that weren't showing up before.

To resolve the issue above, all you need to do is freeze Rails to your application. You should either do this locally on your development machine before you deploy to your DreamHost server or you can do it on the DreamHost server if you've installed that version of Rails to your custom gem install (note that you'll have to re-enable the GEM_HOME and GEM_PATH environment variables to do this if you take this route).

Another common thing to see here is a missing gem:

Loading production environment (Rails 2.3.5) Missing these required gems: aws-s3

This can be resolved by freezing the missing gems to your application.

In summary, the console feature will help you find a large number of problems with your application and will usually get you pointed in the right direction.

Check the Logs
This may seem obvious, but a lot of people don't realize that some very helpful information can be found in the production.log file in your application's log directory. Whenever your application is loading with a Rails application error, this is the place to look as the exception causing the error will show up there. The important bits of the exception are always near the top -- usually within the first couple of lines.

If you find that nothing is being written to the production.log, then there is most likely a problem that's keeping Passenger from loading your app at all. This is most commonly due to an error in the config/database.yml file that's keeping it from connecting to the database. You can get more information about this particular problem here.

If you can't find out what's going on from either the console or the production.log file, Passenger will also sometimes dump some exceptions to the global apache error log that you won't have access to. You can write into support and ask if they can check that log for you in that case. There isn't always something there, but when there is it can prove quite useful in many cases.

A folder named 'public'
Starting in June 2008 all Passenger (mod_rails) enabled sites will need to point to a folder named public. This started after many customers who has no need for passenger / rails innocently enabled it for their domains (thus needlessly increasing the load on the server). If you use symlinks for your site, simply make sure your symlink is named “public”

Stats/PHPMyAdmin missing?
One of the few drawbacks with passenger is that it disabled any re-write rules you or we have setup for your domain. Unfortunately this will break your site's stats and phpMyAdmin pages.

To view your stats you will need to use the command line

To access phpMyadmin you will need to use an alternative MySQL hostname to connect to (any valid mysql hostname not under a passenger enabled domain should do)

Passenger picky with which Rails
One of the benefits with passenger is how quickly and efficiently it can load up the rails libraries. This is also a drawback, as the only version of Rail you will be able to load up is whichever current version we have bundled with passenger (currently 2.0 as of July 2008)

We're sorry, but something went wrong.
Rails can be a bit tricky with its "something went wrong" error. Luckily, it's not hard to track down what went wrong if you know where to look.

The first place to look for any errors in your application is in the logs/production.log (or appropriate environment log file, development.log, test.log or fastcgi-crash.log if running fastCGI). This will tell you exactly what went wrong and where.

Common environment .log errors:

ActionView::TemplateError (undefined method `jibberish' for #) on line #11 of posts/show.html.erb: 8:  <%=h @post.data %> 9: 10:  11: <%= @post.jibberish %> 12: 13: <%= link_to 'Edit', edit_post_path(@post) %> | 14: <%= link_to 'Back', posts_path %> /usr/lib/ruby/gems/1.8/gems/activerecord-2.0.2/lib/active_record/attribute_methods.rb:205:in `method_missing'

Processing PostsController#show [GET] Session ID:  BAh7BzoMY3NyZl9pZCIlMjU0MjFkOGU0ZjZiYjRkZThiNzY3MWc74cf7a1cb49d1c2f59c5314d2963c Parameters: {"action"=>"show", "id"=>"2", "controller"=>"posts"} NoMethodError (undefined method `bad_call' for #): /usr/lib/ruby/gems/1.8/gems/activerecord-2.0.2/lib/active_record/base.rb:1532:in `method_missing'

These types of errors probably mean you either have not updated your database or controller to handle the methods outlined in your views. A possible fix would be to run rake db:migrate or update your view, model or controller file (as appropriate) to correct the failure (line #11 of posts/show.html.erb or the bad_call method listed in the Post controller (under show))

Database connection issues
A properly setup database.yml will look something like this: development: adapter: mysql database: developmentDatabaseName username: DBuserName password: yourSecretPassword host: mysql.yourdomain.com test: adapter: mysql database: testDatabaseName username: DBuserName password: yourSecretPassword host: mysql.yourdomain.com production: adapter: mysql database: productionDatabaseName username: DBuserName password: yourSecretPassword host: mysql.yourdomain.com

Using SQLite is not recommended, more importantly using “localhost” as the host for MySQL will not work.