How to Fix 502 Bad Gateway Error in NGINX

Sometimes, users receive ‘502 Bad Gateway’ error while visiting a website that runs on NGINX server. NGINX server will return ‘502 Bad Gateway’ error when it is unable to communicate with upstream web server. There are several reasons why this can happen. This can happen on a single URL, multiple URLs or across all pages of your website. In this article, we will learn what 502 bad gateway error is, why it is caused and how to fix this problem.

What is 502 Bad Gateway Error in NGINX

NGINX is often used as a reverse proxy, load balancer, or HTTP cache. In these cases, it is used in conjunction with an upstream web application server such as Apache. In such a setup, it is NGINX’s responsibility to forward client requests to upstream web servers, as well as pass the server response back to client.

When NGINX is unable to connect to this upstream web server or receives an invalid response from it, then it gives 502 Bad Gateway Error. This may happen for a single request URL, a group of multiple URLs, or all the URLs on your site. When you get this error for one or more requests, then most likely the upstream server has sent invalid response for these URLs. If you get this response for all URLs on your web page, then probably your upstream web server is down and needs to be inspected.

This error is very similar to 503 Service Unavailable but slightly different. NGINX gives 503 error response when it is unable to connect to backend web server. But in this case, the upstream server is not down but it is still working. It is just that the upstream server is overloaded or under maintenance, and unable to process the request sent from NGINX.

Causes of 502 Bad Gateway Error in NGINX

There are several reasons why users get 502 Bad Gateway Error in NGINX.

1. Configuration Error – This happens if NGINX is incorrectly configured to connect to wrong upstream server or port. In this case, NGINX will send requests to wrong IP address or port, and never receive a valid response. So it will return 502 Bad Gateway response.

2. Server Overload – If backend upstream web server is overloaded with requests and cannot accept any new ones, then it will stop accepting requests from NGINX, or drop previously accepted requests and return 502 Bad Gateway response. In many cases, it may also return 503 Service Unavailable response.

3. Server Down – If your upstream server had crashed or is offline, then also you will get this error. In this case, when NGINX sends client requests to backend server, it does not get any response and so it returns 502 Bad Gateway error. Sometimes, the upstream server may be up and running but unable to send the request further to other upstream processes or applications. So you will need to inspect all possibilities.

4. DNS Issues – In most cases, NGINX uses an IP address to send requests to upstream server. Sometimes, it may also use a domain name to lookup the upstream server. If there is a DNS resolution issue, and the name resolution doesn’t happen properly, then NGINX will be unable to get the correct IP address and forward client request.

5. TLS/SSL Issue – Today, most websites are completely TLS/SSL enabled. It means when NGINX forwards client request to upstream server, it needs to be done over TLS/SSL. In this case, if there is an issue with connection establishment such as during SSL handshake, then it will prevent NGINX from forwarding request to upstream server.

How to Identify 502 Bad Gateway Error

First, you will need to identify the extent of error, that is, which all URLs return this error message. For this purpose, you need to check NGINX server log. This file is typically located at /var/log/nginx/error.log. If you are unable to find the file at this location, open NGINX config file nginx.conf or virtual host config file at /etc/nginx/sites-enabled/ to find the location of NGINX log file.

Use tools like grep or tail to look for phrases like ‘502’ or ‘bad gateway’ or ‘upstream’. Here is a sample command to look for ‘502’ in the last 50 entries of NGINX log.

sudo tail -n 50 /var/log/nginx/error.log | grep '502'

In the output, check if you get this error for all or only a few of the requests. If it is for all URLs then the upstream server may be down or NGINX may be pointing to wrong upstream server IP address. If it is only for a few URLs, then it may be a programming bug in those URLs’ request handlers that you need to fix.

How to Fix 502 Bad Gateway Error in NGINX

Here are some common ways to fix this problem.

1. Check Upstream Server IP

Open NGINX configuration file and check the IP address of upstream server to make sure that NGINX is correctly pointing to the right upstream server IP and port. Otherwise, NGINX may forward client requests to wrong IP address.

2. Check Network Issues

Also check that there is no network issue between NGINX and upstream server. Sometimes, the firewall system on upstream server may block incoming connections from NGINX. So check network and firewall config between NGINX and upstream server.

3. Check DNS Settings

If NGINX server uses domain names to refer to upstream server, then make sure the domain name resolution is correct and fast, else replace domain name with the appropriate IP address.

4. Review Application Code

Sometimes, you may get this error only for some of the URLs and not all of them. This may be because of certain programming bugs in their request handlers. In such cases, you will need to review the code of those request handlers to see why it is causing 502 Bad Gateway error.

5. Check Upstream Timeout Values

If the upstream is getting timed out then also you will get this error. So check if upstream server is getting timed out. If so, then increase server timeout values in the upstream server’s configuration and restart upstream server to apply changes.

Conclusion

In this article, we have learnt about 502 bad gateway error. We have learnt what this error is, the different causes for this problem. We have also learnt the different ways to fix 502 bad gateway error. You can go through them in detail to figure out why your server is giving this problem and use appropriate solution as per your requirement.

Also read:
How to Rewrite URL Parameters in NGINX
How to Redirect Location to Another Domain in NGINX
How to Configure Multiple Host Names in NGINX