HTTP response codes, particularly those representing an error, can be challenging to deal with. While some are simple, others have obtuse or confusing meanings. These codes result from a much broader relationship between the client, the web application, a web server, and untold numbers of outside web services. As you can imagine, 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. The problem is another server upstream, meaning that this server provides service to the system you received the 502 Error from. To help you resolve such errors, here are some troubleshooting tips and potential fixes for common causes. Let's get going!
The Problem is Server-Side
Before we begin, it's worth noting that, like most HTTP response codes, the 502 Error indicates 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 application, you can immediately ignore most client-side code and components. This includes HTML, cascading style sheets (CSS), client-side JavaScript, and so forth. This doesn't apply solely to websites, either.
Behind the scenes, normal web applications will power modern-looking smartphone apps. If you're using such an application and a 502 Bad Gateway Error occurs, the issue will not be related to the app installation on your phone or local testing device. Instead, it will be something on the server-side, which performs most of the logic and processing behind the scenes.
Diagnosing a 502 Bad Gateway Error
As mentioned, a 502 Bad Gateway Error means the client is having difficulty connecting to a server. This means that the server creating the 502 Error is acting as a gateway. Let's take a moment to discuss what a gateway (or proxy) is.
A client will connect to a server via a third-party gateway computer in most HTTP communications. The gateway acts as, well, a gateway, where the client sends messages securely 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 node types 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, the router allows communication from one local network address to another local network address. But when your computer attempts to connect to an IP address outside of this base range, your router's gateway will intercept. Once intercepted, your router will perform the communication between your computer and the remote server.
Perform a Thorough Application Backup
As with anything, it's better to be safe than sorry. As such, it is critical that you perform a complete backup of your application and database before attempting any fixes. Create a complete copy of the application onto a secondary staging server that isn't "live." This will give you a clean testing ground to test fixes without threatening the security of your live application.
Debugging Common Platforms
If a common software package is throwing a 502 Bad Gateway Error, look into the stability of those platforms first. The most common content management systems (CMS) -- like WordPress, Joomla!, and Drupal -- are well-tested out of the box. Once you start making modifications to the underlying extensions or PHP code (the language in which nearly all modern content management systems are written), it's easy to cause an unforeseen issue that results in a 502 Error.
Here are a few tips to help you troubleshoot some of these popular software platforms:
Rollback Recent Upgrades
If you recently updated your CMS before the bad gateway error appeared, consider rolling back to the previous version. Similarly, recently upgraded extensions or modules can also cause server-side issues.
For assistance, simply Google "downgrade [PLATFORM_NAME]" and follow along. However, certain CMSs won’t 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 more popular platforms.
Uninstall New Extensions, Modules, or Plugins
Depending on the CMS, the names of these components will be different, but they serve the same purpose. Extensions help improve the capabilities and features of the platform beyond what it's normally capable of out of the box. Be warned: these extensions can take full control of the system and make virtually any changes. For example, extensions can change PHP code, HTML, CSS, JavaScript, or the database. If you’re seeing a 502 Bad Gateway Error, try uninstalling any new extensions.
Check for Unexpected Database Changes
It's worth noting that, even if you uninstall an extension, this doesn't guarantee that changes made by the extension will be fully reverted. There are scenarios where an extension may modify database records that don't "belong" to the extension itself. The extension may not know how to revert alterations to database records and ignore such things during uninstallation.
Diagnosing these problems can be tricky. Your best course of action is to open the database and look for records likely modified by the extension.
Confirm Proper File Permissions
If the application was working fine before and suddenly an error 502 occurs, permissions are probably not the culprit. However, if modifications were recently made (such as upgrades or installations), it's possible that file permissions were changed. Check out the permissions settings for your application and see if they might be the cause of the 502 Error.
Above all, Google is your friend. Search 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 who has experienced this issue and has shared a solution.
Above all, Google is your friend. Search for specific terms related to your issue, such as the name of your CMS, along with the 502 Bad Gateway Error. Chances are you'll find someone who has experienced this issue and has a solution.
Troubleshooting on the Server-Side
If you aren't running a CMS application or you know that the 502 Bad Gateway Error isn't related to your CMS, 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. 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 spread around the world.
When you ask your computer to connect to airbrake.io, your computer actually checks with a nearby DNS name server to find and connect to a specific IP address. The traffic is routed to an IP address (52.203.232.56, in this case).
Recent changes to your DNS server could result in a 502 Error. Such DNS changes, known as DNS propagation, are not instant and can sometimes take a few hours to propagate.
Server Connectivity Issues
It's entirely possible that a 502 Error indicates that a server somewhere in the chain is down. Most modern applications don't reside on a single server. Instead, they may be spread over multiple systems, or even rely on many third-party services to function. If any one of these servers is down for maintenance or 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. However, automatic firewall services can sometimes mistake perfectly safe and valid content from content delivery networks (CDNs) or elsewhere as malicious. When that happens, your firewall will shut off that stream of content in an instant, leading to a 502 Bad Gateway Error.
Check the Logs
Nearly every web application will keep some form of server-side logs. Application logs contain the history of what the application did, such as requested pages, connected servers, database results, 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.
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 for more information on finding the logs.
Application Code or Script Bugs
The problem may be in the custom code within your application. Try diagnosing and debugging your application by going through your application’s code and server logs. Ideally, make a copy of the entire application to a local development machine and perform a step-by-step debug process. This will allow you to recreate and view the exact scenario that lead to the 502 Error.
If a 502 Bad Gateway Error is popping up within your application, consider an error management tool. Airbrake's error monitoring software provides real-time error monitoring and automatic exception reporting for all your development projects. Airbrake ensures you receive round-the-clock status updates on your application's health and error rates. Plus, no matter what you're working on, Airbrake easily integrates with all the most popular languages and frameworks.
Check out Airbrake's error & performance monitoring software today! See for yourself why so many of the world's best engineering teams use Airbrake by creating your free developer account here. With your free account, you’ll have access to unlimited monitoring for the first 30 days.
Note: We published this post in October 2017 and recently updated it in February 2022.
