502 Gateway error

A 502 Gateway error can occur due to various reasons such as bad code, plugin/theme conflicts, or PHP worker limits. This guide will help you identify and debug these errors using the Staq Panel and take necessary actions to resolve them.

Common Causes of 502 Gateway Errors

There are several reasons why you might encounter a 502 Gateway error, including:

• Bad code inside a plugin or theme
• Plugin/theme conflicts with other plugins
• Upload functions that timeout or enter an infinite loop (due to a bad plugin)
• Issues related to PHP version compatibility
• PHP Workers maxing out
• Distributed Denial-of-Service (DDoS) attacks
• AWS CloudFront blocking requests, triggered by Staq Firewall

Staq provides tools that allow you to diagnose these issues and take appropriate actions.

Using the Debug Tool

To start diagnosing, go to the website’s **Staq Panel** and navigate to Debug. Inside the Debug tool, you can view NGINX Error logs and WordPress logs to see if any errors are recorded.

Enable Debug Mode

If you cannot find any relevant errors, you can enable Debug Mode to reveal hidden issues. Go to the Debug section and click Enable Debug. After enabling it, log into the WordPress backend to see if any error messages appear during operation.

Once you have finished debugging, click Disable Debug to turn off Debug Mode.

Example of a Theme Causing a 502 Error

In the example below, the 502 error was traced back to bad code in a theme. The Debug tool revealed this issue, helping identify the root cause of the problem:

PHP Incompatible Version

A particular plugin may also cause a 502 error as it can be incompatible with the current version of PHP. If it’s possible, try downgrading the PHP version to see if that resolves the issue. You can follow this guide on how to downgrade PHP.

PHP Workers Maxed Out

A common cause of 502 Gateway errors is the site hitting the PHP Workers limit. If your site is maxing out the PHP Workers, you can view:

• data in the Staq UI
• log files

PHP Workers data in UI

To see if PHP Worker limits have been maxed, click PHP Workers under Metrics:

Then, click Parallel PHP Workers and see if there is a long duration of PHP Workers existing your limit. To see your PHP Worker limit, go to PHP Config in the Staq Panel of this site and see Max PHP Workers:

To understand why your hitting PHP Worker limits, you’ll need to download and analyze log files.

Log Files

You can download PHP-FPM log files by following this guide on how to download server log files. Based on the logs, you can see legitimate or illegitimate processes are causing the use of PHP Workers to determine to see if you need to genuinely need to increase PHP Workers.

Increase PHP Workers

Staq makes it easy for you to increase PHP Workers. See this guide on how to increase PHP Workers.

DDoS Attacks

502 Gateway errors may also result from Distributed Denial-of-Service (DDoS) attacks. You can block malicious IP addresses through Staq Firewall.

Reviewing Logs in Firewall

Log into the WordPress website and click Staq Hosting > Firewall. Set a date range to generate a report and review the number of requests and the country of origin.

Blocking Suspicious IP Addresses

Once you’ve reviewed the logs, you can click on the IP address to reveal more details about the requests. Based on this information, you can ban the IP address if it’s identified as suspicious or malicious.
Use the WHOIS IP tool to gather additional information on the IP and determine if it is a WordPress user or making suspicious requests.

From there, you can Ban the IP address.

502 error from AWS CloudFront

Inside the Staq Panel of the website, go to Firewall. Look at both Server or Website Logs which appears in the subtabs:

If the IP address exists there, on the server side, it’s a 503 server error which means the Staq Firewall has banned that particular user. Since the site is rerouting requests via AWS CloudFront, CloudFront then receives a 502 error. By unbanning the IP address will allow CloudFront the request and it should work.

This is the guide on unbanning an IP address.

Conclusion

502 Gateway errors can be caused by a variety of issues, including plugin/theme conflicts, bad code, or maxed-out PHP Workers. Staq provides comprehensive tools to diagnose these problems. Use the Debug tool to assess logs, and if necessary, increase your PHP Workers or block malicious IP addresses using the Firewall.

For further assistance, feel free to reach out to our support team.