Troubleshooting errors using an nginx reverse proxy. Gateway errors: 502, 504

This article is an overview of how nginx works when taking on front-line processing, as both a reverse proxy and direct to PHP processing and can help you troubleshoot related issues. When troubleshooting, it can be helpful to understand how the processing works between nginx and PHP, which is often used for high performance web application hosting, like WordPress.

Common errors that occur that are connected to this configuration:

  • 504 Gateway Timeout
  • Gateway Timeout (504)
  • HTTP Error 504 – Gateway Timeout
  • Gateway Timeout Error
  • 502 bad gateway
  • Bad Gateway

History

Traditional web servers use Apache to respond to HTTP requests, then if there’s a PHP app running (like WordPress), they’ll interact with PHP either via an apache module (direct linked) or by communicating with another running process / server daemon like php-fpm. It looks like this:

Apache -> php-fastcgi

But over the years apache became bloated, eating up lots of ram and disk IO resources, So web developers decided to build replacement HTTP servers, one such server being nginx.

We use nginx because of it’s performance improvements, ensuring our clients’ websites are responding as quickly as possible is important to us. We use a few different configurations: nginx reverse proxy (by default) and nginx direct to PHP for an improved performance config.

Nginx as Reverse Proxy

By default our config goes like this:

nginx -> apache -> php

This is default because nginx is lightweight and can handle many simple queries realllllly fast, yet apache is often needed for compatibility with things like .htaccess files.

Nginx direct to PHP

When we’ve manually optimized a site, the config changes to simply this:

nginx -> php

Wherein we’ve eliminated reliance upon legacy apache-specific features like the use of a .htaccess file and replaced the important apache config within .htaccess with nginx config entered manually into Plesk (most often the transference of rules between web servers comes down to rewrite rules to ensure permalinks / friendly URLs work smoothly).

As you can see by eliminating the middle man, we save a bit on performance.

Troubleshooting Errors

Since in both cases described above, nginx is acting as a gateway and sending requests through to PHP (whether direct or through apache first), if there’s a problem ‘downstream’ — such as with apache or php — you often get a gateway error, like 502 Bad Gateway or 504 Gateway Timeout.

Simple Fix

One simple ‘cover-all’ solution is to directly restart the underlying services. If you don’t have root access to the server, then you can often trigger such a restart by making changes to your website configuration in Plesk. For example, try going to the “PHP Settings” button for your domain, then making any small change there (like increasing memory from 32MB to 35MB) then save your changes. This update triggers a restart of apache and PHP processing and could solve your error!

Note that it may take up to 1 minute (or longer depending on your provider) for the changes to take effect as there may be a specific web server restart interval configured on your server. We rarely configure our restart interval to be longer than 1 minute.

Deeper Code-Related Fixes

The key to troubleshooting these errors is to figure out what, further down the stream, is causing a problem. Some examples:

  1. External Resources: The PHP script is looping or trying to communicate with an external resource that’s taking so long as to reach its timeout, then when it fails to execute properly, it returns to nginx saying “sorry, couldn’t do it” to which nginx will provide a gateway error, like bad gateway (502) or gateway timeout (504).
  2. Limited Buffers: Nginx is configured to not provide enough wiggle room to PHP, such as with too small buffers. Here’s how to configure nginx’s buffers.

To solve issues with External Resources, you’ll need to look into what parts of your software are trying to retrieve external resources, like connections to Google Fonts, or the Twitter API. Similarly, any services that require connectivity on a non-standard port (standard ports are 80 and 443) will require that we open a hole in the firewall to allow the connection through. An example of this is certain payment gateways, or XML API services.

If you’re using WordPress or any other CMS with plugins, be sure to try disabling any plugin that might communicate externally to see if it solves the problem. If you can narrow down which part of the software could be doing this, then we can work on a solution together, like using an alternate plugin, or perhaps opening a port in the firewall if that’s what’s required.

Jordan is a computer, security, and network systems expert and a lover of all things web and tech. Jordan consults with project management for software companies. Jordan is a founder and managing partner at Websavers Inc.

2 Comments

  1. Qasim Abbas on April 14, 2017 at 5:04 am

    @Jordan, had the same issue in my previous website but it is fine now.

Leave a Comment