502 Bad Gateway NGINX: Fix PHP-FPM Errors | MetricFire

Seeing “502 Bad Gateway” on your NGINX server? This guide explains what causes NGINX–PHP-FPM gateway errors and how to fix them step by step. You’ll also learn how to monitor performance to prevent future outages.

Introduction

Encountering a 502 Bad Gateway error when using NGINX with PHP-FPM can be frustrating. This guide delves into the common causes of this error and provides actionable steps to diagnose and resolve the issue effectively.

NGINX Error 502 Bad Gateway is a standard error among website users. There are several possible reasons for this error and several ways to resolve it. In this article, we will examine the leading causes and how users and web developers can address them.

To prevent and troubleshoot NGINX 502 Bad Gateway errors caused by PHP-FPM, it's crucial to have real-time visibility into your server's performance to gain a complete observability picture. Learn how pairing time-series metrics with corresponding log lines is the fastest path to detecting and resolving issues before they impact users:

• Monitor NGINX Performance with OpenTelemetry.
• Nginx Performance Monitoring: Loki Logs and Telegraf Metrics

Use MetricFire's platform to analyze your system's performance and troubleshoot errors. Book a demo with our team for more detailed information about MetricFire and how to integrate it with your system; sign up for a MetricFire free trial, or read more about monitoring your NGINX webserver with Telegraf here.

Key Takeaways

1. NGINX Error 502 Bad Gateway is an error message that indicates the server is receiving an error from another server and cannot connect to PHP-FPM, or PHP-FPM is not responding.
2. Using PHP-FPM with NGINX can improve website performance and reduce resource consumption.
3. Possible reasons for the error include a non-running NGINX or PHP-FPM, a firewall blocking requests, a domain name not being allowed, or the server being unavailable.
4. To solve the error, website visitors can reload the page, clear the browser cache and delete cookies, try using a different browser, or restart the router.
5. MetricFire's platform can monitor NGINX statuses, and its Telegraf plugin allows users to visualize their NGINX server's status and 502 errors.

What Does a 502 Bad Gateway NGINX Error Mean?

A 502 Bad Gateway error indicates that NGINX, acting as a reverse proxy, received an invalid response from an upstream server—in this case, PHP-FPM. This typically means that NGINX was unable to establish a successful connection with PHP-FPM or that PHP-FPM failed to respond appropriately

A 502 Bad Gateway error means that the server you are accessing received an error from another server. This happens when one server acts as a proxy to receive information from another. When connecting to another server, it returns an error. NGINX returns error 502 if it cannot connect to PHP-FPM or PHP-FPM is not responding.

There are different names for the 502 error that you can see on different sites. For example:

• HTTP Error 502 - Bad Gateway.
• HTTP 502.
• 502 Service Temporarily Overloaded.
• Temporary Error (502).
• 502 Bad Gateway NGINX.
• 502 Bad Gateway.
• Error 502.
• 502 Proxy Error.

Also, the page's appearance that displays the 502 error can be customized on different sites in the same way as it is done for the 404 not found error. There are various causes of error 502. Below, we will examine the main ones and possible ways to fix this error.

What is PHP-FPM used for?

PHP-FPM (PHP-FastCGI Process Manager) is a web request processing tool for PHP applications. With NGINX, PHP-FPM can significantly increase website performance and reduce resource consumption.

If you are using PHP-FPM, PHP works as an isolated service. Web requests are processed over a TCP/IP socket, NGINX only handles HTTP requests, and PHP-FPM interprets PHP code. The use of separate services is essential to improve efficiency.

Common Causes of NGINX 502 Bad Gateway (PHP-FPM)

1. PHP-FPM Service Not Running

If PHP-FPM isn't running, NGINX cannot forward requests to it, resulting in a 502 error.

Check PHP-FPM Status:

systemctl status php-fpm

If the service is inactive, start it:

sudo systemctl start php-fpm

2. NGINX Unable to Connect to PHP-FPM

Misconfigurations in NGINX can prevent it from connecting to PHP-FPM.

Verify NGINX Configuration:

Ensure that the fastcgi_pass directive in your NGINX configuration matches the PHP-FPM listening address. For example:

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

If PHP-FPM is configured to listen on a Unix socket, adjust accordingly:

fastcgi_pass unix:/run/php/php7.4-fpm.sock;

3. PHP-FPM Timeouts

Long-running PHP scripts may exceed the timeout settings, causing PHP-FPM to terminate the process prematurely.

Adjust Timeout Settings:

In your PHP-FPM pool configuration (e.g., /etc/php/7.4/fpm/pool.d/www.conf), consider increasing the request_terminate_timeout value:

request_terminate_timeout = 60s

Also, ensure that NGINX's fastcgi_read_timeout is set appropriately in your server block:

fastcgi_read_timeout 60s;

4. Resource Exhaustion

High server load or insufficient resources can cause PHP-FPM to become unresponsive.

Monitor Server Resources:

Use tools like top, htop, or vmstat to monitor CPU and memory usage. If resources are maxed out, consider optimizing your application, upgrading server resources, or implementing caching mechanisms.

5. Firewall or Security Software Interference

Firewalls or security software may block communication between NGINX and PHP-FPM.

Check Firewall Settings:

Ensure that the necessary ports (e.g., 9000 for PHP-FPM) are open and not blocked by firewall rules.

6. DNS Resolution Issues

If NGINX is configured to connect to PHP-FPM via a hostname, DNS resolution failures can result in 502 errors.

Test DNS Resolution:

Use the dig or nslookup commands to verify that the hostname resolves correctly.

Possible reasons for 502 Bad Gateway

Let's take a look at some possible reasons for the 502 Bad Gateway error.

NGINX is not running

If you see error 502, check if NGINX is running. To do this, run the following command:

systemctl status nginx

If the response shows the status as inactive (dead), start NGINX.

PHP-FPM is not running

The following is the reason for the 502 error: PHP-FPM is not running. If you are on Linux, you can check if PHP-FPM is running using the following command:

ps aux | grep php-fpm

If no PHP-FPM processes are displayed due to this command, you must run PHP-FPM to resolve error 502.

PHP-FPM timeout expires

If the server takes too long to respond, a 502 error can be caused by a PHP-FPM timeout. In this case, PHP-FPM closes the connection before the response is sent, and NGINX returns a 502 error. To fix this problem, you can increase the PHP-FPM timeout, or you will have to research your application and figure out why it has not responded for too long.

Firewall blocks requests

A firewall can block communication between the edge servers and the origin server. Some DDoS protection systems or your CMS's security plugins can block server requests.

A domain name is not allowed.

The domain name is not resolved to the specified IP address or all IP addresses. In this case, you need to change the DNS server and wait for the changes to propagate and become active globally.

Server is unavailable

The original server is down, or there is no connection to this server.

Step-by-Step Fixes for NGINX 502 Bad Gateway Errors

Most often, the 502 error occurs due to issues on the website's side. However, there are times when the issue lies with the user's device. You can check whether you only have connection problems or whether other people cannot connect to this website. To do this, use one of the tools that check the site's status and whether it is working. For example, use one of the following tools or similar ones: isitdownrightnow.com or downforeveryoneorjustme.com. To learn more about the cause of error 502, you can examine the NGINX log file on your computer (/var/log/nginx/error.log).

If You’re a User:

If you are the only one experiencing connectivity issues, there are several things you can do as a website visitor to resolve the 502 error.

1. Reload the page in the browser. The 502 error is often temporary, and a simple reboot can help.
2. Clear browser cache and delete cookies. The browser can save old or corrupted files and data that can cause the 502 error.
3. Try using a different browser. The error may occur only in the specific browser you are using; it will not occur in another browser.
4. Restart your computer and network equipment. Perhaps this is the problem, and the error will disappear after a reboot.
5. Check plugins and extensions in your browser. If you use any plugins or extensions, and the website works in another browser, they may block the connection. Disable all installed plugins and extensions, and recheck the connection.
6. Change your DNS server. Changing the DNS server may resolve the 502 error. You can choose Open DNS or Google DNS servers.

If You’re a Developer:

In most cases, error 502 occurs for all users because the problem is on the website. As a web developer, you can do the following:

1. Check if your server is available.
2. Check the firewall logs for unusual crashes.
3. If you are using Cloudflare, your visitors may receive a 502 Bad Gateway error when a certain limit is reached. Try to disable Cloudflare.

Preventing 502 Errors with Real-Time Monitoring

Implementing robust monitoring can help detect and address issues before they escalate.

Utilize MetricFire's Monitoring Tools:

MetricFire offers tools such as Telegraf, OpenTelemetry, and Loki Logs to monitor NGINX and PHP-FPM performance metrics. By setting up real-time dashboards and alerts, you can proactively manage your server's health and respond swiftly to anomalies.

Monitoring your system metrics with Hosted Graphite by MetricFire

To identify bottlenecks and troubleshoot errors such as error 502, it is helpful to monitor your system's metrics and the technologies used in your application. MetricFire has an open-source platform that provides the tools to monitor and analyze your system's metrics. MetricFire offers Hosted Graphite and Hosted Grafana. Grafana is a web-based analytics and data visualization application. It allows you to create customizable dashboards, including diagrams, graphs, and notifications. You can easily monitor your Nginx instance using MetricFire.

Let's take a look at some of the main features of Grafana:

1. Dashboard templates. You can design your dashboard using templates as if you were writing code. With templates, you can use the same design in different environments.
2. Annotations. You can create logs and comments on your chart manually or automatically.
3. Custom Plugins. Grafana can install external plugins to expand its basic functionality.
4. SQL support. With SQL support, you can easily pull data from various data sources.
5. Alerts. Grafana can send users notifications about essential incidents.

Graphite is a tool for collecting, storing, and processing metrics. It can also be used as a data source for Grafana. Grafana has an advanced Graphite query editor that lets you write various queries, add functions, change function parameters, execute complex nested queries via query links, and more.

Hosted Graphite and Grafana let you track your system performance in real time. MetricFire offers hosting for both tools, so you can focus on your system's performance and monitor its metrics in your browser.

FAQs About NGINX 502 Bad Gateway

Q1: What causes a 502 Bad Gateway NGINX error?
A 502 error happens when NGINX can’t get a valid response from an upstream service like PHP-FPM. Causes include PHP-FPM not running, timeouts, or misconfiguration.

Q2: How do I check if PHP-FPM is running?
Use systemctl status php-fpm or ps aux | grep php-fpm on Linux. If inactive, start the service with sudo systemctl start php-fpm.

Q3: Can a firewall cause NGINX 502 Bad Gateway?
Yes. Firewalls or security plugins may block communication between NGINX and PHP-FPM on port 9000.

Q4: How can I monitor NGINX and PHP-FPM to prevent 502 errors?
MetricFire’s Hosted Graphite and Grafana dashboards, combined with Telegraf or OpenTelemetry, offer real-time performance tracking and alerting.

Q5: Is 502 Bad Gateway a client-side or server-side error?
It’s usually a server-side issue caused by backend service failures or misconfiguration, though clients may see it during temporary network disruptions.

Conclusion

A 502 Bad Gateway error in NGINX when using PHP-FPM is often a symptom of underlying issues such as service downtime, misconfigurations, or resource constraints. By systematically diagnosing and addressing potential causes and implementing proactive monitoring solutions like those offered by MetricFire, you can ensure the reliability and performance of your web applications.

Book a demo with MetricFire experts or sign up for the free trial today to learn more about our features.