What Is a “502 Bad Gateway” Error?
Let’s start with the basics. A 502 Bad Gateway error happens when Nginx (a web server) tries to talk to another server (like PHP or another backend service) but doesn’t get a good response.
Think of Nginx like a waiter at a restaurant. If the kitchen (the backend) doesn’t reply, the waiter can’t bring you food. So Nginx says, “Bad Gateway.”
Some terms you might not know:
- Nginx: A web server that handles requests and sends responses to users.
- Gateway: A bridge that connects two systems.
- 502: A type of error code meaning something went wrong between two servers.
When Does This Happen?
From what I’ve seen, this error can show up when:
- The backend (like PHP-FPM or another service) is down.
- Nginx is misconfigured.
- There’s a timeout because the backend is too slow.
- The server is under heavy load.
I’ve run into this while setting up WordPress, Laravel, and even simple HTML pages that use PHP.
Step 1: Check if the Backend Is Running
Most times, this error means the backend is not running. If you’re using PHP-FPM, start by checking it:
sudo systemctl status php8.2-fpm
Change php8.2-fpm to match your version.
If it’s not active, start it:
sudo systemctl start php8.2-fpm
Also, make sure it starts on boot:
sudo systemctl enable php8.2-fpm
Still not sure? Restart it just to be safe:
sudo systemctl restart php8.2-fpm
This fixed the issue for me more than once.
Step 2: Check Nginx Configuration
If the backend is fine, Nginx might be pointing to the wrong socket or port.
Here’s what to check:
Open your Nginx config file:
sudo nano /etc/nginx/sites-available/default
Look for a section like this:
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}
Make sure the socket path is correct. You can check the actual socket file:
ls /run/php/
If you see a different version (like php7.4-fpm.sock), update the config to match.
Or maybe your setup uses TCP. It could look like this:
fastcgi_pass 127.0.0.1:9000;
Use this if your PHP-FPM is set up with a port instead of a socket.
After changing the config, test it:
sudo nginx -t
If you get no errors, reload Nginx:
sudo systemctl reload nginx
Step 3: Look at the Logs
Still seeing the error? Logs can help.
Try checking Nginx’s error log:
sudo tail -n 20 /var/log/nginx/error.log
You might see messages like “connect() failed” or “no such file or directory.” These give clues.
You can also check PHP-FPM logs:
sudo tail -n 20 /var/log/php8.2-fpm.log
Again, change the version to match your system.
Step 4: Restart Everything
Sometimes a fresh start helps. Try restarting Nginx and PHP-FPM:
sudo systemctl restart nginx
sudo systemctl restart php8.2-fpm
Then try visiting your website again. Has it worked yet?
Step 5: Check Firewall or SELinux
In some cases, security settings block connections.
Try these:
- Check if a firewall is blocking port 9000.
- If using SELinux, it might block access to the socket.
I once had a problem where SELinux silently stopped Nginx from talking to PHP. Took me hours to figure out.
You can test SELinux mode with:
getenforce
If it returns “Enforcing,” you might need to allow HTTP connections:
sudo setsebool -P httpd_can_network_connect 1
This helps Nginx talk to other services.
Step 6: Check Server Load
If your server is slow or busy, it might not respond in time.
You can see system usage with:
top
Or use:
htop
(highly recommend installing htop for better visuals)
Look at CPU and memory. If they’re full, your backend might be timing out.
Try restarting heavy services or upgrading your server if it happens often.
Three Things to Try First
When I see a 502 error, I usually try these first:
- Restart Nginx and PHP-FPM
- Check if the socket path is correct
- Look at the logs for hints
Three Common Causes
Based on my experience, these are the most common problems:
- PHP-FPM is not running
- Nginx is pointing to the wrong socket or port
- The server is under too much load
Three Ways to Prevent It
To stop 502 errors from coming back:
- Monitor your services regularly (tools like
monitoruptime-kumahelp) - Keep server software updated
- Set up alerts so you know if a service goes down
Wrapping Up
Fixing a 502 Bad Gateway error on Nginx isn’t as hard as it seems. I’ve made many of these mistakes myself, and every time I learned something new. It’s like solving a puzzle.
Take it step by step. Start with the basics: is PHP-FPM running? Is Nginx pointing to the right place? Are there any error messages?
If you stay calm and check each part, you’ll usually find the fix.
What were you doing when the 502 error showed up? Were you updating something or moving files around?
Let me know if you need help digging into a specific case. I’d be happy to share more.
