Nginx 911: How to Fix 502 Bad Gateway & 413 Entity Too Large Errors

AI development environment on Ubuntu

Server management is 90% smooth sailing and 10% panic. The two most common panic moments on a Joy Services VPS are the 413 Upload Error and the 502 Bad Gateway.

Here is exactly what they look like, why they happen, and the copy-paste commands to fix them.

Issue #1: "413 Request Entity Too Large"

The Scenario: You try to upload a large WordPress theme, a plugin, or a video file.

Browser Error
413 Request Entity Too Large nginx/1.18.0 (Ubuntu)

The Fix: Nginx blocks uploads larger than 1MB by default. We need to raise that limit.

1. Edit the Main Config:

Bash
root@joy:~# sudo nano /etc/nginx/nginx.conf

2. Add `client_max_body_size`:
Find the http { ... } block and add the line below:

Nginx Config
http { ... client_max_body_size 64M; ... }

3. Test and Reload:

Bash
root@joy:~# sudo nginx -t && sudo systemctl reload nginx
Expected Output
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful

Issue #2: "502 Bad Gateway"

The Scenario: You visit your site and see a white screen with black text.

Browser Error
502 Bad Gateway nginx/1.18.0 (Ubuntu)

The Fix: This means Nginx is working, but PHP (or Node.js) has crashed. Nginx is knocking, but nobody is answering.

1. Check the Status:

Bash
root@joy:~# sudo systemctl status php8.3-fpm
The Problem (Output)
● php8.3-fpm.service - The PHP 8.3 FastCGI Process Manager Active: failed (Result: exit-code)

2. Restart the Service:

Bash
root@joy:~# sudo systemctl restart php8.3-fpm
Expected Output
● php8.3-fpm.service Active: active (running)

(Note: If you use Node.js, run pm2 restart all instead.)

Issue #3: "404 Not Found" on Sub-pages

The Scenario: Your homepage works fine. But when you click "About Us" or "Contact," you get a 404 error.

Browser Error
404 Not Found nginx/1.18.0 (Ubuntu)

The Fix: Nginx treats /about-us as a real folder. We need to tell it to ask WordPress instead.

1. Edit Your Site Config:

Bash
root@joy:~# sudo nano /etc/nginx/sites-available/your_domain.com

2. Fix the `location /` Block:
Replace your existing location / block with this one:

Nginx Config
location / { try_files $uri $uri/ /index.php?$args; }

3. Verify and Restart:

Bash
root@joy:~# sudo nginx -t && sudo systemctl restart nginx
Expected Output
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful