NGINX errors and how to fix them

When running a website on NGINX, you may occasionally encounter errors that prevent the site from working properly. This guide covers the most common ones — 502 Bad Gateway, 504 Gateway Time-out, and 413 Request Entity Too Large — and shows step-by-step how to fix them on VPS or dedicated servers.

502 Bad Gateway

What it means: NGINX cannot get a response from the backend (PHP-FPM, Apache, Node.js, uWSGI, etc.).

Most common causes:

• Backend service is stopped or crashed
• Wrong socket path or port in config
• Incorrect permissions on the socket
• Not enough memory or worker processes in PHP-FPM

How to fix:

1. Check the status of PHP-FPM (or your backend):

sudo systemctl status php-fpm
# or for specific version
sudo systemctl status php8.1-fpm

2. Restart the service:

sudo systemctl restart php-fpm
# or php8.1-fpm

3. Verify the socket path in NGINX and PHP-FPM configs:

   • NGINX: fastcgi_pass unix:/run/php/php8.1-fpm.sock;
   • PHP-FPM (/etc/php/8.1/fpm/pool.d/www.conf): listen = /run/php/php8.1-fpm.sock

4. Fix permissions if needed:

sudo chown www-data:www-data /run/php/php8.1-fpm.sock
sudo chmod 660 /run/php/php8.1-fpm.sock

5. Test and reload NGINX:

sudo nginx -t && sudo systemctl reload nginx

504 Gateway Time-out

What it means: NGINX waited too long for a response from the backend and timed out.
Most common causes:

• Slow PHP script execution
• Slow database queries
• High server load

How to fix:

1. Increase timeouts in your site config (in server or location block):

proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
fastcgi_read_timeout 300s;  # for PHP

2. Optimize PHP-FPM (in /etc/php/8.1/fpm/pool.d/www.conf):

pm.max_children = 50          # increase as needed
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
request_terminate_timeout = 300

3. Restart services:

sudo systemctl restart php-fpm
sudo systemctl reload nginx

4. If the issue is with a specific script — optimize DB queries or add caching for heavy pages.

413 Request Entity Too Large

What it means: Client is trying to upload a file larger than NGINX's allowed limit (default 1 MB).
Common causes: Uploading large files (photos, videos, backups, archives).

How to fix:

1. Increase the limit in your site config (or in /etc/nginx/nginx.conf in http block):

client_max_body_size 64M;  # or 128M, 512M, 1G, etc.

2. Reload NGINX:

sudo nginx -t && sudo systemctl reload nginx

3. Also increase PHP limits in php.ini (/etc/php/8.1/fpm/php.ini):

upload_max_filesize = 64M
post_max_size = 64M

Restart PHP-FPM:

sudo systemctl restart php-fpm

How to reload NGINX properly

• Always check config first:

sudo nginx -t

• Graceful reload (no downtime):

sudo systemctl reload nginx

or

sudo nginx -s reload

• Full restart (only if reload doesn't help):

sudo systemctl restart nginx

Useful notes

• Always back up configs before changes: sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
• After changes, check logs: /var/log/nginx/error.log and /var/log/nginx/access.log