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 currently acting as a gateway or proxy did not receive a timely response from another server further upstream. As with most HTTP response codes, it can be challenging to determine the exact cause of a 504 Gateway Timeout Error. 

Throughout this article, we'll examine the 504 Gateway Timeout Error and look at a few troubleshooting tips and potential fixes.

The Problem is Server-Side

All HTTP response status codes in the 5xx category are server error responses. Similar to the 502 Bad Gateway Error, a 504 Gateway Timeout Error means that something has gone wrong with a gateway or proxy server 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 upstream is located higher in the overall server hierarchy than a downstream server. The terms "upstream" and "downstream" refer to the relative distance of a server from your device. The further the server is from your device, the more "upstream" it is.

Since the 504 Gateway Timeout Error indicates that something has gone wrong within your application's server, we can largely disregard the client side. If you're having trouble with your application, you can disregard most client-side code, including HTML, CSS, and JavaScript. This doesn't apply solely to websites, either. 

Many web applications behind the scenes power smartphone apps with a modern-looking user interface. If a 504 Gateway Timeout Error occurs, the issue isn't related to the app installed on your phone or local testing device. Instead, it will be something on the server-side.

The problem may not be with the specific web server your application is running on. Instead, it's possible that every aspect of your particular application (along with its servers) are working flawlessly. However, a 504 Gateway Timeout Error could still occur if an upstream server is experiencing problems.

Start With a Thorough Application Backup

As with anything, it's better to be safe than sorry. As such, it is critical that you perform a full backup of your application and database before attempting any fixes. If you have the capability, create a complete copy of the application onto a secondary staging server that isn't "live.” This will create a safe environment to test possible solutions to the problem, without jeopardizing your live application.

Diagnosing a 504 Gateway Timeout Error

As mentioned before, a 504 Error means that a server upstream did not receive a "timely" response from another server further along upstream. The server providing the 504 Gateway Timeout Error is acting as a gateway. 

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 are 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 clients, servers, and other nodes within the (virtual) vicinity.

Believe it or not, most homes with Internet access have an active gateway. Your local home network, which is likely set up 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. 

Problems arise 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 cause 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 relies on third-party services, which are typically located elsewhere on additional upstream servers. Any of the upstream servers your client (web browser) is connecting through may be down or experiencing issues at this time, causing delays in processing and a 504 Status Code.

Troubleshooting on the Server-Side

• Here are some additional tips to help you troubleshoot your server to find the cause of a 504 Error: 

  • Recent DNS Changes - The Domain Name System (DNS) is a decentralized naming system for devices connected through a network. In short, the DNS associates domain names (e.g. airbrake.io) to specific IP addresses. It then stores that association in a series of authoritative name servers worldwide. If you recently changed your DNS server or moved your site, that could be the cause of the 504 Error. 
  • Server Connectivity Issues - Most modern applications don't reside on a single server. Instead, they are spread over multiple systems and/or rely on third-party services. If any one of these servers is 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. Essentially, it decides which traffic is safe and which could be malicious. In some situations, a firewall configured somewhere on your application’s network might be preventing some form of critical traffic from getting through. 
  • Check the Logs - Nearly every web application will keep some form of server-side logs. Application logs are the history of what the application did and contains requested pages, connected servers, and database results. Server logs are related to the actual hardware that is running the application. These logs will often provide details about the health and status of all connected services or even just the server itself. 
  • Application Code or Script Bugs - Try to diagnose where the issue may be coming from by 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. 

If you see a 504 Gateway Timeout Error, it means you probably need an error management tool. Such tools automatically detect these and other errors in the future. They 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 web dashboard provides you with 24/7 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 features such as customizable exception parameters and error filterings allow you to gather the errors that matter most. 

Check out Airbrake's error monitoring software today and create a free dev account! See for yourself why so many of the world's best engineering teams use Airbrake to revolutionize their exception handling practices!

Note: We published this post in October 2017 and recently updated it in July 2022.