502 Bad Gateway Error
Any 50x error means that some request to the server didn’t return a proper result. A 502 specifically means that there was a bad gateway. At WP Engine, this gateway usually refers to the relationship between NGINX and PHP.
On the WP Engine platform, the 502 Bad Gateway error typically signals an issue between the uncached PHP processing of the request and the request being served back to the browser. Servers have a specific number of PHP Workers available to process uncached requests at any given time. If a request being processed by a PHP Worker is rejected for taking too long to complete or cannot complete, this causes the 502 Bad Gateway error.
About 502 Errors
When a 502 occurs on WP Engine this is almost always one of two things:
- Instant 502 – The error message displays immediately after an action
- Sig terms, graceful restarts, and/or segmentation faults have occurred causing the connection to break. These can happen for a variety of reasons most commonly bad code, but can also include uncached request load, or too many process time-outs.
- Long 502 – The error message takes around 60 seconds to appear after an action
- The request was killed by the Long Process Killer after 60 seconds
Before diagnosing a 502 we advise checking the site’s access logs to confirm the 502 shown in the browser was actually returned in the access logs, and not a different error code. Access logs are located in the User Portal.
Diagnose 502 Errors
Review the site’s error logs to see if there have been any code errors which might explain the timeout, as well as killed queries. If these logs don’t help, start narrowing down root causes. For example, turning off all plugins and seeing if the error still exists will help determine if the error is caused by a plugin or the theme.
Combating 502 errors can be an art in itself. Since the causes of these errors can be deep in the code of a site and not easily identifiable, we highly recommend consulting with a developer. For help finding a developer, WP Engine has a list of recommended consultants.
If immediate help is needed with 502 errors, please contact Support via 24/7 chat in the User Portal.
We’ve put together a helpful workflow for diagnosing 502s:
Consistent 502 Errors
Is the 502 error instant? This is most likely due to a code issue.
- If the 502 occurs only on a custom login path, this may be due to a caching and security conflict. Reach out to WP Engine Support to have the “Login Protection” feature disabled and the custom path excluded from server caching.
- If the 502 occurs on other pages, a plugin or theme conflict may be occurring. Try disabling plugins/setting a default theme then see if the issue persists.
Is the 502 error long (~60 seconds)? This is most likely due to a process is being killed by our server timeout.
- If running an import/export, it will need to be reduced in size
- Try disabling plugins/setting a default theme then see if the issue persists.
- Query Monitor may be of assistance here in locating a slow/long query.
502 Errors on Specific Pages
Try disabling plugins/setting a default theme one at a time to see if the issue persists.
502 Errors at Recurring Times
Cross-check the timing of the cron jobs that are receiving the 502 errors
- There may be crons running too long and using workers that could instead be broken up into smaller chunks.
Cross-check traffic peaks times and review any custom cache exclusions added via Support
- Traffic combined with a large number of uncached pages will overwork the server and cause more 502 evictions at times of high traffic.
- Custom cache exclusions can be reviewed on the Cache page of the User Portal.
Random 502 Errors
The database may be the issue, try optimizing the database.
Is object caching enabled? Try disabling the object cache.
- If this works, leave object caching off until the autoloaded data in the database is reduced.
Prevent 502s
The best way to prevent issues with 502 Bad Gateway errors is to ensure the site is healthy. Following WordPress best practices for site health will help prevent code conflicts and keep the site secure.
Simple steps like updating Plugins, Themes, and WordPress itself can help ensure site health. These updates should be tested in a staging or test environment first to prevent code conflicts on the production site.
Last, regularly audit the plugins and settings and delete anything unnecessary. Fewer installed plugins means a smaller codebase to maintain and fewer opportunities for code conflicts.
Disable Server Timeout
The 60-second timeout is in place to ensure our servers are able to serve the maximum amount of concurrent requests. Without a timeout in place, we’ve seen requests take minutes to even hours to complete. With the continued performance of the site in mind, we will not be able to disable the server timeout which may be causing the 502s. This timeout is programmed at the root of our platform. It is in place to ensure optimal server health, speed, and uptime.
NEXT STEP: Learn how to troubleshoot using the WP Engine SSH gateway
