If your Ruby application won't start because of a missing gem, then you must install it locally using Bundler. For more information about using Bundler, please visit the following page:
This article describes common errors you may encounter when using Passenger.
Application not restarting
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.
Broken pipe error
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.
Production log isn't written to
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.
Missing connection settings
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.
Using a socket connection rather than a host
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
Passenger can't find rails
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.
ERB comments cause the beginning of your view to vanish
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).
Enabling Passenger error-friendly pages
Passenger error-friendly pages help you troubleshoot upgrade issues. To enable, add the following to an .htaccess file within the application: