One of the most frustrating errors the sysadmin comes across when working with Nginx is the 502 error. The text accompanying this error is ‘Bad Gateway’, which, unfortunately, doesn’t say much about what might have gone wrong. In contrast, the other errors clearly say that the resource or page was not found, or that you don’t have permissions to view a particular resource.
In this article, then, we’ll look at the 502 Bad Gateway error in Nginx in more detail, and will suggest some time-tested ways of troubleshooting it.
What is the 502 Bad Gateway error?
When a server responds to an HTTP request, the class of response codes tells a lot. For instance, response like 4xx are to do with bad requests; similarly, the 5xx series is reserved for server errors. This means if you get a 500 or 502 response, it’s not your fault – something went wrong with the server.
In the 502 error, what the server is trying to tell you is that it failed to connect with an important service through a connecting ‘gateway.’ If this sounds too generic to be helpful, that’s just the nature of the beast; depending on what stack you’re running and how Nginx is set up serve requests, this error would mean different things.
In the most common case, for example when your new WordPress installation throws this error, it means that Nginx wasn’t able to communicate properly with the PHP (or PHP-FPM) service. Next, let’s look at an example of how we would resolve this error in PHP.
Resolving the 502 Bad Gateway Error in Nginx and PHP
There are several steps you need to systematically check for resolving the 502 Bad Gateway error.
PHP-FPM isn’t present
In the first scenario, perhaps the config file you have provided to Nginx says that it must connect through PHP-FPM, while that service is actually not installed on your server. This is very common with new server installs.
To resolve this, all you need to do is (assuming you’re on Ubuntu 16.04):
$ sudo apt install php-fpm
$ sudo service php-fpm restart
$ sudo service nginx restart
After this, try accessing the URL again, and most likely, the error will be gone.
PHP-FPM isn’t able to connect to port or socket
Another typical case is when you have the Nginx config file asking it to listen on a socket, whereas in reality that socket doesn’t even exist. Another possibility is that the config file tells Nginx to connect over port 9000 (an extremely common setting) whereas the FPM process is configured to send output through a socket file.
To see if there’s this mismatch, open the PHP-FPM configuration file. For PHP 7.1 on Ubuntu 16.04, the location is /etc/php/7.1/fpm/pool.d/www.conf and look for the following line:
listen = /run/php/php7.1-fpm.sock
Now, check if the file /run/php/php7.1-fpm.sock actually exists. If it doesn’t, simply create it and set the relevant permissions:
# touch /run/php/php7.1-fpm.sock
# chown :www-data /run/php/php7.1-fpm.sock
# chmod 775 /run/php/php7.1-fpm.sock
Once this is done, try restarting FPM and Nginx, and things should work.
APC not working
Sometimes the Alternative PHP Cache (APC) is a really bad idea and is best avoided. It’s often the cause of 502 Bad Gateway errors. If you’re running APC, please disable it and replace with more robust caching schemes (Memcache is a good alternative).
Depending on your environment, you’d need to do similar detective work to see what has gone wrong with Nginx connection. The best place to start is always the Nginx error logs.