Passenger troubleshooting

This article describes common errors you may encounter when using Passenger.

Using Passenger with Node.js allows you to load your site on port 80 or 443. However, this only works if your application is named app.js.

This generally isn't actually a problem. It's only perceived as a problem. In Passenger 2.1 the behavior of the restart mechanism changed. Now Passenger simply checks the modification timestamp on the restart.txt file. If it's more recent than the last time it checked, it restarts. The file is not removed. This was done so that restarting applications would work seamlessly on NFS shares.

On lower traffic sites, you can usually still visually see the application restarting by "priming" a page (loading it a couple times in your browser), touching the restart.txt file and then loading that page again. It should take a noticeably longer time to load than it had the previous couple of times. This won't really work on live sites that are getting traffic though as it's entirely possible another person's request restarted the application by the time you test it yourself.

If you get an error message mentioning a broken pipe with the exception class PhusionPassenger::Railz::ApplicationSpawner::Error as depicted in the image, you're most likely running into memory limit problems. What's happening is the request being processed by Passenger caused your user memory limit on the server to be exceeded and the Rails process that was handling that request was killed. Unfortunately, there isn't a much that can be done about this since even a very basic Rails application requires a lot of memory up front. This happens even more frequently if you have more than one Rails application hosted from the same account. The best way to ensure that you don't run into this problem is to move your Rails sites over to a VPS. That gives you guaranteed, scalable memory that you can adjust until your memory needs are met.

This is most often caused by a misconfigured database.yml file. If your database.yml file isn't configured correctly, Passenger dies before your application is loaded. As such, you get no helpful error messages from Passenger and your production.log file isn't touched.

Some versions of Passenger really don't like it if your database.yml file doesn't at least include settings (they can be blank) for all environments. The symptom of this happening is your application endlessly loading with no output to the production.log file. So, make sure you leave the connection information for all environments in your database.yml file -- even if you're only using the production settings.

This mistake is simply not changing from using a socket connection to a host. The default MySQL connection information looks like this:

production:
  adapter: mysql
  encoding: utf8
  reconnect: false
  database: bar_production
  pool: 5
  username: root
  password: 
  socket: /tmp/mysql.sock

As you can see, it's configured to use a socket connection by default. You need to make sure you replace that line with correct host, username, and password information for a database. You can find this information on the MySQL Databases page. A correct configuration might look like this:

production:
  adapter: mysql2
  encoding: utf8
  reconnect: false
  database: bar_production
  pool: 5
  username: exampleuser
  password: jWr873dnaiu12
  host: mysql.example.com

Another common mistake is simply having a necessary parameter misnamed. This can happen easier than it sounds because when you generate a Rails application it defaults to generating a sqlite3 database.yml configuration file. You have to manually specify that you want a MySQL file (rails --database mysql <projectname>) or you'll have to change it manually. Since a lot of people don't realize this, they end up changing it after the fact and sqlite3 config files don't have username or host parameters. Here's what a default sqlite3 section looks like:

production:
  adapter: sqlite3
  database: db/production.sqlite3
  pool: 5
  timeout: 5000

So, it would be easy enough to modify that to look something like this:

production:
  adapter: mysql2
  database: bar_production
  pool: 5
  user: exampleuser
  password: jWr873dnaiu12
  host: mysql.example.com

See the problem? In that configuration the "username" parameter was called "user" instead. This is a very common error and easy to miss. It should actually look like this:

production:
  adapter: mysql2
  database: bar_production
  pool: 5
  username: exampleuser
  password: jWr873dnaiu12
  host: mysql.example.com

There have been some instances where this error pops up when deploying applications that include their own config.ru, such as Fat Free CRM. If you come across this error, try renaming the config.ru and see if the error goes away.

You may be tempted to begin a view with a comment to help you remember which file you're editing. This can be helpful if, for example, you have "index.html.erb" under many different controllers. You may be tempted to do this.

This view is broken:

<% # Help controller index: %>
 <p> blah blah blah...
 <%= link_to "help topic 1", help_topic_one %>
 more blah blah blah</p>

What happens is that the erb processor summarily treats as a comment everything up to the next erb directive. It won't appear in the output stream sent to the browser. In the above example, the view starts with the link, eliminating everything prior to that:

<a href="/">help topic 1</a> more blah blah blah</p>

As you can see by the dangling </p> tag, this can easily break your DOM structure, causing numerous problems both for your CSS directives and any Prototype/jQuery/Ajax commands you're running.

This bug can surprise you because the above view renders exactly as it should under Mongrel in a development environment.

The solution, is to eliminate the comment or replace it with an old-school HTML comment (the <!-- kind).

Passenger error-friendly pages help you troubleshoot upgrade issues. To enable, add the following to an .htaccess file within the application:

PassengerFriendlyErrorPages on