Troubleshooting Passenger + Apache and Node.js

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

Table of contents

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 (not the per-vhost) Apache error log file. This is typically located in /var/log/apache2/error_log.

You can find out the exact location of the error log by running passenger-config --detect-apache2.

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

Not finding anything useful in the Passenger error log? Please read Troubleshooting logging problems.

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.

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

PassengerPreStart (Apache)

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

Next, run full path of the command using either sudo or rvmsudo:

$ sudo /somewhere/bin/passenger-status

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

$ rvmsudo /somewhere/bin/passenger-status

macOS: The installer cannot locate MAMP's Apache

Symptoms

The installer finds Apache 2 development headers at /Applications/MAMP/Library/bin/apxs. However, Apache cannot be found. The installer also outputs the following error:

cannot open /Applications/MAMP/Library/build/config_vars.mk:
No such file or directory at /Applications/MAMP/Library/bin/apxs line 218.

Cause

Your MAMP installation seems to be broken. In particular, 'config_vars.mk' is missing.

Solution

Please read this forum topic to learn how to fix this problem. See also this bug report.

Apache reports a "403 Forbidden" error

Please refer to Static assets such as images and stylesheets aren't being displayed.

Static assets such as images and stylesheets aren't being displayed

Static assets are accelerated, i.e. they are served directly by Apache and do not go through the application. There are two reasons why Apache doesn't serve static assets correctly:

Your Apache configuration is too strict, and does not allow HTTP clients to access static assets. This can be achieved with an Allow from all directive in the correct place. For example:

<Directory "/webapps/mycook/public">
   Options FollowSymLinks
   AllowOverride None
   Order allow,deny
   Allow from all
   Options -MultiViews
   # Uncomment this if you're on Apache >= 2.4:
   #Require all granted
</Directory>

Apache cannot access my app's files because of SELinux errors

On Red Hat Enterprise Linux and CentOS, Apache is locked down by a security mechanism called SELinux. This security mechanism works on top of normal Unix permissions. In order for Apache to be able to access your app's files, you must set the proper SELinux labels on your files.

First, ensure that your app does not live in a home directory. It is not possible to allow Apache to read files from your home directory.

Second, give your app's files the httpd_sys_content_t labels by running the following command:

sudo chcon -R -h -t httpd_sys_content_t /path-to-your-app

The application thinks its not on SSL even though it is

Rails and many other frameworks infers whether it's running on SSL through the CGI environment variable HTTPS. Apache always sets this variable when on SSL, except when SSL is incorrectly configured.

Most Apache installations already configure SSL by default on port 443 (conf/extra/httpd-ssl.conf). Some people think they can save some typing in subsequent SSL vhost blocks, and omit important options like 'SSLEngine on', like this:

# httpd-ssl.conf contains something like:
# <VirtualHost _default_:443>
#     SSLEngine on
#     ...
# </VirtualHost>
Include conf/extra/httpd-ssl.conf

<VirtualHost *:443>
    ServerName www.example.com
    DocumentRoot /webapps/example/public
</Virtualhost>

This is wrong! In each SSL vhost block you must re-specify all the SSL options. Otherwise Apache won't properly detect the vhost as an SSL vhost block. Here's the corrected example:

Include conf/extra/httpd-ssl.conf

<VirtualHost *:443>
    ServerName www.example.com
    DocumentRoot /webapps/example/public
    SSLEngine on
    ...more SSL options here...
</Virtualhost>

Conflicting Apache modules

Some Apache modules are not compatible with Passenger. They may be loaded simultaneously with Passenger, but they may not be enabled simultaneously in the same virtual hosts.

mod_userdir

mod_userdir is not compatible with Passenger at the moment.

MultiViews (mod_negotiation)

MultiViews is not compatible with Passenger. You must disable MultiViews for all Passenger hosts.

Troubleshooting Passenger + Apache and Node.js

First things to try

1 Check the Passenger log file

2 Check the application log file

3 Upgrade Passenger to the latest version

4 Consult the in-depth topics

5 Out of ideas? Try the support resources

Common problems

Why does the first request take a long time?

Symptoms

Cause

Solution

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

Symptoms

Cause

Solution

Recommended reading

macOS: The installer cannot locate MAMP's Apache

Symptoms

Cause

Solution

Apache reports a "403 Forbidden" error

Static assets such as images and stylesheets aren't being displayed

Apache cannot access my app's files because of SELinux errors

The application thinks its not on SSL even though it is

Conflicting Apache modules

mod_userdir

MultiViews (mod_negotiation)

VirtualDocumentRoot

Common problems specific to Node.js

I get "Error: http.Server.listen() was called more than once"