One of the most difficult things for a new comer to Ruby on Rails to deal with is trying to figure out what’s wrong when your application won’t work and, even in development mode, reports the vague and dreaded “Rails application failed to start properly” error. I’ve found, after having felt the pain over the course of the last year a few times, that the problem usually boils down to one of a few things.

Eliminate Web Server Issues
Make sure your web server is running properly. If you’ve fired up a Webrick server, watch your terminal window to see if it’s indeed responding to requests. You should see some kind of activity if you’re hitting your application through a browser. If you’re using Apache or Lighttpd, make sure that these two are working properly as well by watching their access and error logs.

If you think the web server is responding, try pulling up a static file. Go to http://localhost:3000/images/rails.png or some other static, non Ruby resource that you know should be there. If you don’t get back what you expect in Webrick, it’s possible that Webrick isn’t functioning properly, and that the shebang line is incorrect (I’ll talk about that in a second). If you’re using Apache or Lighttpd, make sure your paths to your application are correct, and make sure that Apache or Lighttpd have permission to serve up the dispatch.cgi or dispatch.fcgi files.

If you’re using FCGI with either Apache or Lighttpd, watch the FastCGI crash log. If you don’t have a crash log, double check your FCGI config in your Apache or Lighttpd config file and make sure it’s logging FCGI errors.

Getting Things Right
Make sure that the first line, the shebang line, in scripts/server points to your ruby executable. This should be correct but can sometimes be wrong, especially if you didn’t use the rails executable to build the application (which can happen often if you downloaded the code from another server with different paths).

In public/ make sure that dispatch.fcgi or dispatch.cgi also has the correct shebang.

In public/ you should also make sure that you have the hidden .htaccess file if you’re going to be using Apache and that it’s sending requests to dispatch.fcgi if you’re using FCGI, and dispatch.cgi if you’re not. Note that often times when you check out applications from Subversion repositories, the .htaccess file might not be in the revision (because Subversion ignores hidden files by default on initial imports).

If you have a database built and you’re expecting to get some results back, make sure your config/database.yml file is correct, and that your database server is responding.

Execute Valid Code
It’s possible to write code that breaks a Rails application before Rails can show you a more informative error. Make sure your code is valid and that you don’t have any Ruby syntax errors.

Watch Logs
You should always be watching your log/development.log when developing, and if you begin to run into issues that aren’t clearly apparent in the development log, begin watching both your FastCGI errors log and your web server access and error logs to make sure things are working properly.

If All Else Fails
Use the Rails community page as your starting point. Check the Wiki, ask questions on #rubyonrails or send an email to the Rails email list. Make sure that people know exactly what your environment is like. For instance, I develop Rails on OS X 10.4.3 using Ruby 1.8.4 and Rails 1.0 running under Apache 1.3. Describe the circumstances that led to the error, and whether or not you saw errors in your array of logs, and anything else that might be relevant. Usually it doesn’t get to this stage, but when it does it’s good to know there a lot of people willing to help you figure it out.