Troubleshooting Passenger

Relevant selections for this article:

This page provides guidance on what to do when you encounter problems.

Table of contents

• Loading...

First things to try

1 Check the Passenger log file

One of the first things you should do upon encountering a problem, is to check the Passenger log file. The log file is where Passenger prints to when it encounters a problem or when it wants to tell you something.

This log file contains:

• Passenger info, warning and error messages.
• Everything that the application writes to STDOUT and STDERR. This typically consists of errors that the application encounters during startup, but not errors that it encounters when it's handling requests.

The Passenger log file is the global Nginx error log file. This is one specified by the error_log directive in the main context (that is, not the one inside the http context). The file is typically located in /var/log/nginx/error.log.

Or, if you configured the passenger_log_file directive, then the log file is in the referenced file.

2 Check the application log file

The application or web framework may have its own log file that is independent from the Passenger log file. You should also check that file to see whether your application or web framework has logged any important messages.

For example, Ruby on Rails logs to log/development.log and log/production.log. When an error occurs during request handling, it is typically logged here. Note that this file does not contain errors that Rails encounters during startup – those kinds of errors are typically written to STDERR, which means they end up in the Passenger log instead.

Note that Passenger runs applications in the "production" environment by default (that is, Passenger sets RAILS_ENV, RACK_ENV, NODE_ENV and related environment variables "production"). So if you're using Rails, please be sure to check production.log instead of development.log.

3 Upgrade Passenger to the latest version

Some problems are caused by bugs in Passenger. Passenger is under active maintenance and development, so there is a chance that – assuming you really ran into a bug – the bug is already fixed. Please upgrade Passenger to the latest version and check whether the problem is still there.

If you suspect that your problem is a bug in Passenger, and upgrading didn't fix it, please report the bug to our Github issue tracker.

If upgrading Passenger didn't help, and you don't think your problem is caused by a bug, then please continue with this troubleshooting guide.

4 Consult the in-depth topics

Passenger takes care of a lot of things for you under the hood. If you don't know what Passenger does, then problems may seem opaque. Try learning more about the activities that Passenger perform; it may help you with understanding the problem and with troubleshooting.

5 Out of ideas? Try the support resources

If you are stuck with a problem, please do not hesitate to contact one of the support resources. Passenger has a friendly community of users who look out for each other. We – Passenger's authors – are also ready to help you whenever we can.

Stack Overflow

Post a question on Stack Overflow if you are experiencing problems. Support on Stack Overflow is provided by the community, and our own developers also watch Stack Overflow on a regular basis. But support here is provided on a best-effort basis, so sometimes a bit of patience will help. Be sure to use the "passenger" tag.

Github issue tracker

If you are experiencing a problem that you believe is a bug, please report it here.

Security vulnerabilities email address

Please report security vulnerabilities to security@phusion.nl. We will do our best to respond to you as quickly as we can, so please do not disclose the vulnerability until then.

Priority support for Enterprise customers

If you are a Passenger Enterprise customer, then you are eligible for basic priority support. Please submit your support ticket via the interface in the customer area.

For most customers, this basic priority support has a response time of 3 working days, with a maximum of 1 support incident per month. Please consult your contract for the exact support level that you are eligible for.

Premium support contracts

We also provide premium support contracts for those who desire higher support levels, for example 24x7 phone support with a response time of 1 hour.

Common problems

Why does the first request take a long time?

Symptoms

The first request to your application takes more time than usual. Subsequent requests have the normal speed.

Cause

Passenger starts your application the first time it is accessed, not during web server startup. Some applications can take several seconds to start. If you're using Ruby on Rails, then needing 10 seconds to start your application is normal. On slow or heavily loaded servers, or in case of large and heavy applications, the startup time may be even longer.

Solution

Use the passenger_pre_start configuration option.

I get "command not found" when running a Passenger command through sudo

Symptoms

Passenger commands can be found as a normal user, but not when run through sudo:

$ passenger-status
...some output, but no "command not found" error...
$ passenger-install-apache2-module
...some output, but no "command not found" error...
$ sudo passenger-status
sudo: passenger-status: command not found
$ sudo passenger-install-apache2-module
sudo: passenger-install-apache2-module: command not found

Cause

The operating system looks up commands using the PATH environment variable. However, sudo resets all environment variables to a default value, dictated by sudo. If Passenger was installed to a location that is not in the default sudo PATH value, then sudo will not be able to find the Passenger commands.

In addition, if you installed Passenger using a Ruby interpreter that was installed through RVM, then you must use rvmsudo instead of sudo. As a rule, when you're an RVM user, always use rvmsudo instead of sudo.

Solution

Execute the command using its full path. You can use which as a normal user to lookup the full path:

$ which passenger-status
/somewhere/bin/passenger-status

$ sudo /somewhere/bin/passenger-status

# -OR, if you're using RVM:-

$ rvmsudo /somewhere/bin/passenger-status

Recommended reading

When using sudo, you will probably run into similar "command not found" issues in the future, with components other than Passenger. We strongly recommend you to learn about environment variables so that you know what to do in the future.

Upon accessing the web app, Nginx reports a "404 Not Found" error instead of displaying my web app

Symptoms

You visit your web app, but instead of seeing your web app, you see a 404 Not Found error page. In addition, you also see a piece of text that the 404 Not Found error page is generated by Nginx.

If you look in the Nginx error log, you see an error message like this:

2015/07/02 20:14:17 [error] 31746#0: *80 "/app/public/index.html" is not found (2: No such file or directory), client: 127.0.0.1, server: 127.0.0.1, request: "GET / HTTP/1.1", host: "foo.com"

There are several common causes for this problem.

Cause and solution #1

You did not enable Passenger in the corresponding server block with passenger_enabled on.

To solve this problem, please specify passenger_enabled on in your Nginx configuration file, inside your app's server block.

Cause and solution #2

If you did enable Passenger with passenger_enabled on, then maybe the problem is that you did not configure Nginx to enable the Passenger module. Please check whether your Nginx configuration file contains the passenger_root option. If it doesn't, please add it.

Cause and solution #3

If you did enable Passenger with passenger_enabled on, and passenger_root is also specified in your Nginx config file, then it is likely that Passenger encountered an error during initialization. If Passenger was not able to initialize, then it will log the error, and then Nginx will behave as if Passenger was never installed in the first place. As a result, Nginx will try to serve static files in your web app's static files directory, fail to do so, then report a 404 Not Found error.

To solve this problem, please open the Passenger log file and look for any error messages there. The error messages will tell you why Passenger failed to initialize. Please take action accordingly.

Cause and solution #4

Make sure Passenger recognizes your application. If autodetection fails, for example because you are using non-standard filenames, you might have to specify additional options.

Note that if you are upgrading from a Passenger version below 5, autodetection requires a config.ru to be present, as specified in the upgrade notes.

Upon accessing the web app, Nginx reports a "Permission denied" error

Symptoms

A typical error message looks like this:

2013/10/21 17:16:03 [alert] 98687#0: *1 Cannot stat
'/Users/phusion/Sites/rack.test/config.ru': Permission denied (errno=13); This
error means that the Nginx worker process (PID 99064, running as UID 70) does
not have permission to access this file. Please read this page to learn how to
fix this problem:
https://www.phusionpassenger.com/library/admin/nginx/troubleshooting/?a=upon-accessing-the-web-app-nginx-reports-a-permission-denied-error;
Extra info, client: 127.0.0.1, server: www.foo.com, request: "GET / HTTP/1.1",
host: "www.foo.com"

Cause

Passenger tries to access your application directory in order to find out what language it's written in. This access is initiated from inside an Nginx worker process. This error indicates that the Nginx worker process does not have the proper permissions to access your application's root directory.

Solution

You need to relax permissions to that the Nginx worker process can access your application directory, by making the directory group- and world-executable:

sudo chmod g+x,o+x /Users/phusion/Sites/rack.test

You also need to ensure that all parent directories are also 'executable' by the Nginx process:

sudo chmod g+x,o+x /Users/phusion/Sites
sudo chmod g+x,o+x /Users/phusion
sudo chmod g+x,o+x /Users

Common problems specific to Ruby

The application reports during startup that it cannot find a gem

Symptoms

Despite the fact that you have already run bundle install, you see an error page that contains the following messages:

It looks like Bundler could not find a gem. Maybe you didn't install all the gems that this application needs. To install your gems, please run:

  bundle install

...

Could not find XXX in any of the sources (Bundler::GemNotFound)

Causes and solutions

The most common cause of this problem, is that your system has multiple Ruby interpreter (or multiple RVM gemsets), and your application is not being run under the correct Ruby interpreter. The bundle install command installs gems into a directory that is specific to one Ruby interpreter, so when your app is being run under a different Ruby interpreter, Bundler cannot find its gems.

To solve this problem, you must explicitly tell Passenger what Ruby interpreter to use. You can do this with the passenger_ruby configuration option.

The second most common cause of this problem, is that your application is being run under the wrong user. The bundle install command often installs gems into a user-specific directory. So if Passenger for some reason runs your app as a different user than the one that invoked bundle install, Bundler may not be able to find its gems. Read Sandboxing apps with Unix user accounts to learn why Passenger may run your application as a different user.

To solve this problem, you must explicit tell Passenger what user to run as by using the passenger_user configuration option.

If this didn't solve your problem, try following the tips in the error message. Also be sure to double check the settings printed on the error page. Be sure to double check all environment variables, user IDs, etc and check whether they are what you expect.

Common problems specific to Ruby on Rails

This section lists some common problems that are specific to the Ruby on Rails web framework.

The "About your application's environment" link does not work

The "About your application's environment" link only works if the application is started in the "development" environment. Passenger starts the application in the "production" environment by default.

Use the rails_env configuration option to change this.

The Rails application reports that it's unable to start because of a permission error

Please check whether your Rails application's directory has the correct permissions. By default, Rails applications are started as the owner of the file config.ru, except if the file is owned by root. If the file is owned by root, then the Rails application will be started as 'nobody' (or as the user specified by passenger_default_user).

Please read User account sandboxing for details.

The Rails application cannot find my database

If your Rails application cannot find your database, then you probably didn't configure Passenger correctly, or didn't configure your database.yml correctly. By default, Passenger runs Rails applications in 'production' mode, so please either make sure that your database.yml contains an entry for the production environment, or configure Passenger to start your app in the 'development' environment.