504 Gateway Timeout

504 Gateway Timeout Error: What It Is and How to Fix It

A 504 Gateway Timeout Error is an HTTP response status code indicating that a server, which is currently acting as a gateway or proxy, did not receive a timely response from another server further upstream. As with most HTTP response codes that indicate an error like this, it can be difficult to determine the exact cause of a 504 Gateway Timeout Error. There are dozens of possible HTTP status codes used to represent the complex relationship between the client, a web application, a web server, and often multiple third-party web services, so determining the cause of a particular status code can be a challenge, even under the best of circumstances.

Throughout this article we’ll examine the 504 Gateway Timeout Error by looking at a few troubleshooting tips and potential fixes for common problems that might be causing this issue, so let’s get started!

The Problem is Server-Side

All HTTP response status codes that are in the 5xx category are considered server error responses. Similar to the 502 Bad Gateway Error we’ve looked at in the past, a 504 Gateway Timeout Error indicates that something has gone wrong with a gateway or proxy server that is further upstream. In general networking parlance, an upstream server is a server that provides a service to (i.e. is accessed by) another server. Thus, a server that is upstream is located higher in the overall server hierarchy than a server that is downstream. Another way to think of upstream versus downstream is their relative proximity to your device (i.e. the client) — the greater the number of hops required to transfer data from your client to the server in question, the further upstream that server is located.

Since the 504 Gateway Timeout Error indicates that something has gone wrong within the server of your application, we can largely disregard the client side of things. If you’re trying to diagnose an issue with your own application, you can immediately ignore most client-side code and components, such as HTML, cascading style sheets (CSS), client-side JavaScript, and so forth. This doesn’t apply solely to web sites, either. Many smart phone apps that have a modern looking user interface are actually powered by a normal web application behind the scenes; one that is simply hidden from the user. If you’re using such an application and a 504 Gateway Timeout Error occurs, the issue isn’t going to be related to the app installed on your phone or local testing device. Instead, it will be something on the server-side, which is performing most of the logic and processing behind the scenes, outside the purview of the local interface presented to the user.

That said, it isn’t necessarily the case that the specific web server that your application is running on is the source of the problem. Instead, it’s entirely possible that every aspect of your particular application (along with its servers) are working flawlessly, but a 504 Gateway Timeout Error could still be occurring if an upstream server is experiencing problems.

Start With a Thorough Application Backup

As with anything, it’s better to have played it safe at the start than to screw something up and come to regret it later on down the road. As such, it is critical that you perform a full backup of your application, database, and so forth, before attempting any fixes or changes to the system. Even better, if you have the capability, create a complete copy of the application onto a secondary staging server that isn’t “live,” or isn’t otherwise active and available to the public. This will give you a clean testing ground with which to test all potential fixes to resolve the issue, without threatening the security or sanctity of your live application.

Diagnosing a 504 Gateway Timeout Error

As mentioned, a 504 Gateway Timeout Error means that a server that is upstream to one that you (the client) are connecting to did not receive a “timely” response from another server further along upstream. In this scenario, this indicates that the server providing the 504 Gateway Timeout Error is acting as a gateway, so let’s take a moment to discuss what a gateway (or proxy) is. In most HTTP communications, a client will connect to a server via a third-party gateway computer. The gateway acts as, well, a gateway, by which messages from the client can be securely sent to the server, and vice-versa. A gateway acts as a node within the larger network web, connecting and routing communications between multiple client, server, and other node types within the (virtual) vicinity.

Believe it or not, most homes with Internet access even have an active gateway. Your local home network, which is likely setup through a router (or router+modem hybrid), typically assigns IP addresses to all the devices on your network using the base address of 192.168.1.*, where the asterisk changes depending on the device. In most cases, communication from one such local network address to another local network address is allowed, but when your computer attempts to connect to an IP address outside of this base range, your router’s gateway will intercept it and perform the communication between your computer and the remote server on your behalf.

In some situations, the web server running your application may be the cause of the problem. This is particularly true when your server is running either a combination frontend+backend server setup (such as Nginx and Apache), or the web server is relying on third-party services, which are typically located elsewhere on additional upstream servers. Any of the upstream servers that your client (web browser) is connecting through may be down or experiencing issues at this time, which could cause a delay in processing and lead to the 504 Gateway Timeout Error you’re seeing.

Above all, Google is your friend. Don’t be afraid to search for specific terms related to your issue, such as the name of your application’s CMS or web server software, along with 504 Gateway Timeout Error. Chances are you’ll find others who have experienced this issue and have potentially been provided a solution.

Troubleshooting on the Server-Side

Here are some additional tips to help you troubleshoot what might be causing the 504 Gateway Timeout Error to appear on the server-side of things:

  • Recent DNS Changes – The Domain Name System (DNS) is a decentralized naming system for devices connected through a network (even a massive network, such as the Internet itself). In short, the DNS associates domain names (e.g. airbrake.io) to specific IP addresses, and stores that association in a series of authoritative name servers spread around the world. Thus, when you ask your computer to connect to airbrake.io, your computer actually checks with a nearby DNS name server to find out what the specific IP address (internet resource) is that it should connect to. From your perspective it’s going directly to airbrake.io, but behind the scenes the traffic is routed to an IP address (52.203.232.56, in this case). Consequently, your application may present a 504 Gateway Timeout Error if your site has made recent changes to its DNS server, which is a result of changing host servers or moving the site to a different IP address. Such DNS changes, known as DNS propagation, are not instant and can sometimes take a few hours to propagate throughout all the authoritative name servers.
  • Server Connectivity Issues – While it may sound simple, it’s entirely possible that a 504 Gateway Timeout Error simply indicates that a server somewhere in the chain is down or unreachable for whatever reason. Most modern applications don’t reside on a single server, but may, instead, be spread over multiple systems, or even rely on many third-party services to function. If any one of these servers are down for maintenance or otherwise inaccessible, this could result in an error that appears to be from your own application.
  • Improper Firewall Configuration – A firewall is a basic security device that monitors network traffic and acts as a gatekeeper, deciding which traffic is safe and which could be malicious. In most cases, all potentially harmful traffic is stopped (and may be logged for network admin use). In some situations, it’s entirely possible for a firewall configured somewhere on the network in which your application is running to be preventing some form of critical traffic from getting through. This is particularly true for applications that rely on content delivery networks (CDNs), which act as a third-party host for “heavy” content like images or videos, hosting that content on behalf of your application, so your application can maintain its speed and efficiency. However, automatic firewall services can sometimes perform false positives, mistaking perfectly safe and valid content from CDNs or elsewhere as malicious, thereby shutting off that stream of content in an instant, which could lead to a 504 Gateway Timeout Error.
  • Check the Logs – Nearly every web application will keep some form of server-side logs. Application logs are typically the history of what the application did, such as which pages were requested, which servers it connected to, which database results it provides, and so forth. Server logs are related to the actual hardware that is running the application, and will often provide details about the health and status of all connected services, or even just the server itself. Google “logs [PLATFORM_NAME]” if you’re using a CMS, or “logs [PROGRAMMING_LANGUAGE]” and “logs [OPERATING_SYSTEM]” if you’re running a custom application, to get more information on finding the logs in question.
  • Application Code or Script Bugs – If all else fails, it may be that a problem in some custom code within your application is causing the issue. Try to diagnose where the issue may be coming from through manually debugging your application, along with parsing through application and server logs. Ideally, make a copy of the entire application to a local development machine and perform a step-by-step debug process, which will allow you to recreate the exact scenario in which the 504 Gateway Timeout Error occurred and view the application code at the moment something goes wrong.

No matter what the cause, the appearance of a 504 Gateway Timeout Error coming from your own web application is a strong indication that you may need an error management tool to help you automatically detect these and other errors in the future. Such mechanisms can even alert you and your team immediately when an error occurs. Airbrake’s error monitoring software provides real-time error monitoring and automatic exception reporting for all your development projects. Airbrake’s state of the art web dashboard ensures you receive round-the-clock status updates on your application’s health and error rates. No matter what you’re working on, Airbrake easily integrates with all the most popular languages and frameworks. Plus, Airbrake makes it easy to customize exception parameters, while giving you complete control of the active error filter system, so you only gather the errors that matter most.

Check out Airbrake’s error monitoring software today and see for yourself why so many of the world’s best engineering teams use Airbrake to revolutionize their exception handling practices!