502 Bad Gateway Error: What It Is and How to Fix It

HTTP response codes, particularly those that represent an error, can be difficult to deal with. While some are simple, others have obtuse or confusing meanings and, worst of all, since these codes are the result of a much broader relationship between the client, the web application, a web server, and untold numbers of outside web services, pinning down exactly what a given error indicates can be a challenge in the best of circumstances.

In this article we’ll explore the 502 Bad Gateway Error, which indicates that a server somewhere within the server stack — specifically, one which is acting as a gateway or proxy itself — received an invalid response from a different server. Typically, the root of the problem is another server upstream, meaning that the problematic server provides service to the system you received the 502 Bad Gateway Error from. To help you resolve such errors, we’ll examine a few troubleshooting tips and potential fixes for common causes, so let’s get going!

The Problem is Server-Side

Before we begin, it’s worth noting that, like most HTTP response codes, the 502 Bad Gateway Error is an indication that something has gone wrong within the server of your application, as opposed to 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 502 Bad Gateway Error occurs, the issue isn’t going to be related to the app installation 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.

Diagnosing a 502 Bad Gateway Error

As mentioned, a 502 Bad Gateway Error means that a server that is upstream to one that you (the client) are connecting to has run into trouble. In this scenario, this means that the server providing the 502 Bad Gateway 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.

Perform 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.

Debugging Common Platforms

If you’re running common software packages on the server that is throwing the 502 Bad Gateway Error, you may want to start by looking into the stability and functionality of those platforms first. The most common content management systems — like WordPress, Joomla!, and Drupal — are all typically well-tested out of the box, but once you start making modifications to the underlying extensions or PHP code (the language in which nearly all modern content management systems are written in), it’s all too easy to cause an unforeseen issue that results in a 502 Bad Gateway Error.

Here are a few tips to help you troubleshoot some of these popular software platforms:

  • Rollback Recent Upgrades – If you recently updated the content management system itself just before the 502 Bad Gateway Error appeared, you may want to consider rolling back to the previous version you had installed when things were working fine. Similarly, any extensions or modules that you may have recently upgraded can also cause server-side issues, so reverting to previous versions of those may also help. For assistance with this task, simply Google “downgrade [PLATFORM_NAME]” and follow along. In some cases, however, certain CMSs don’t really provide a version downgrade capability, which indicates that they consider the base application, along with each new version released, to be extremely stable and bug-free. This is typically the case for the more popular platforms, so don’t be afraid if you can’t find an easy way to revert the platform to an older version.
  • Uninstall New Extensions, Modules, or Plugins – Depending on the particular content management system your application is using, the exact name of these components will be different, but they serve the same purpose across every system: improving the capabilities and features of the platform beyond what it’s normally capable of out of the box. But be warned: such extensions can, more or less, take full control of the system and make virtually any changes, whether it be to the PHP code, HTML, CSS, JavaScript, or database. As such, it may be wise to uninstall any new extensions that may have been recently added. Again, Google the extension name for the official documentation and assistance with this process.
  • Check for Unexpected Database Changes – It’s worth noting that, even if you uninstall an extension through the CMS dashboard, this doesn’t guarantee that changes made by the extension have been fully reverted. This is particularly true for many WordPress extensions, which are given carte blanche within the application, including full access rights to the database. Unless the extension author explicitly codes such things in, there are scenarios where an extension may modify database records that don’t “belong” to the extension itself, but are instead created and managed by other extensions (or even the base CMS itself). In those scenarios, the extension may not know how to revert alterations to database records, so it will ignore such things during uninstallation. Diagnosing such problems can be tricky, but I’ve personally encountered such scenarios multiple times, so your best course of action, assuming you’re reasonably convinced an extension is the likely culprit for the 502 Bad Gateway Error, is to open the database and manually look through tables and records that were likely modified by the extension.
  • Confirm Proper File Permissions – If the application was working fine before and suddenly this error occurs, permissions are not a very likely culprit. However, if modifications were recently made (such as upgrades or installations), it’s possible that file permissions were changed or are otherwise incorrect, which could cause an issue to propagate its way throughout the application and eventually lead to a 502 Bad Gateway Error. The vast majority of servers use Unix-based operating systems, so have a look here, or elsewhere on the web, for more information on setting up proper permissions for application files and directories to keep things secure, while also allowing your application access where it’s needed.

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, along with the 502 Bad Gateway Error. Chances are you’ll find someone (or, perhaps, many someones) who have experienced this issue and have potentially been provided a solution.

Troubleshooting on the Server-Side

If you aren’t running a CMS application — or even if you are, but you’re confident the 502 Bad Gateway Error isn’t related to that — here are some additional tips to help you troubleshoot what might be causing the issue 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 (, in this case). Consequently, your application may present a 502 Bad Gateway 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 502 Bad Gateway 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 502 Bad Gateway 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 502 Bad Gateway Error occurred and view the application code at the moment something goes wrong.

Ultimately, if a 502 Bad Gateway Error is popping up within your application, you should strongly consider an error management tool that will help you automatically detect exceptions and report them to you and your team the moment they occur. 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!

Monitor Your App Free for 30 Days

Discover the power of Airbrake by starting a free 30-day trial of Airbrake. Quick sign-up, no credit card required. Get started.