502 Bad Gateway troubleshooting in Nginx - Commands & Configuration

Introduction

A 502 Bad Gateway error happens when a server acting as a gateway or proxy gets an invalid response from the upstream server. This error stops users from accessing the website or service. Troubleshooting helps find and fix the cause quickly.

When your website shows a 502 error instead of loading normally

When your Nginx server is set up as a reverse proxy but the backend app is not responding

When you recently changed backend server settings and users report connection problems

When you want to check if your backend service is running and reachable

When you want to verify Nginx configuration for proxying requests

Commands

Check if the Nginx service is running properly on your server.

Terminal

systemctl status nginx

Expected Output

● nginx.service - A high performance web server and a reverse proxy server

   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)

   Active: active (running) since Fri 2024-06-14 10:00:00 UTC; 5min ago

 Main PID: 1234 (nginx)

    Tasks: 3 (limit: 1152)

   Memory: 5.0M

   CGroup: /system.slice/nginx.service

           ├─1234 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;

           ├─1235 nginx: worker process

           └─1236 nginx: worker process

Test if the backend server (running on port 8080) is responding correctly.

Terminal

curl -I http://localhost:8080

Expected Output

HTTP/1.1 200 OK

Server: ExampleBackend

Content-Type: text/html

Content-Length: 612

Connection: keep-alive

Check Nginx configuration syntax to ensure there are no errors causing the 502 error.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

View the last 20 lines of the Nginx error log to find clues about the 502 error.

Terminal

tail -n 20 /var/log/nginx/error.log

Expected Output

2024/06/14 10:05:00 [error] 1235#1235: *45 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.10, server: example.com, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:8080/", host: "example.com"

→

-n 20 - Show last 20 lines of the log file

Key Concept

If you remember nothing else from this pattern, remember: a 502 error means Nginx cannot reach or get a valid response from the backend server.

Common Mistakes

Not checking if the backend server is running before troubleshooting Nginx.

If the backend is down, Nginx will always return 502 errors regardless of its own configuration.

Always verify the backend service is up and responding before changing Nginx settings.

Ignoring Nginx error logs and only checking access logs.

Error logs contain detailed reasons for 502 errors, which access logs do not show.

Check /var/log/nginx/error.log to find connection or configuration errors causing 502.

Not testing Nginx configuration syntax after changes.

Syntax errors can cause Nginx to fail or misroute requests, leading to 502 errors.

Run 'nginx -t' after any config change to ensure syntax is correct.

Summary

Check if Nginx service is running using 'systemctl status nginx'.

Verify backend server responds correctly with 'curl -I http://localhost:8080'.

Test Nginx configuration syntax using 'nginx -t'.

Review Nginx error logs with 'tail -n 20 /var/log/nginx/error.log' to find connection issues.