Errori NGINX e come risolverli

Quando si gestisce un sito web con NGINX, possono comparire errori che ne compromettono il corretto funzionamento. Questa guida tratta i più comuni — 502 Bad Gateway, 504 Gateway Time-out e 413 Request Entity Too Large — e mostra passo dopo passo come risolverli su un VPS o su server dedicati.

502 Bad Gateway

Cosa significa: NGINX non riesce a ottenere una risposta dal backend (PHP-FPM, Apache, Node.js, uWSGI, ecc.).

Cause più comuni:

• Il servizio backend è fermo o è andato in crash
• Percorso del socket o porta errati nella configurazione
• Permessi non corretti sul socket
• Memoria o processi worker insufficienti in PHP-FPM

Come risolvere:

1. Controlla lo stato di PHP-FPM (o del tuo backend):

sudo systemctl status php-fpm
# o per una versione specifica
sudo systemctl status php8.1-fpm

2. Riavvia il servizio:

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

3. Verifica il percorso del socket nelle configurazioni di NGINX e PHP-FPM:

   • 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. Correggi i permessi se necessario:

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

5. Testa e ricarica NGINX:

sudo nginx -t && sudo systemctl reload nginx

504 Gateway Time-out

Cosa significa: NGINX ha atteso troppo a lungo una risposta dal backend ed è scaduto il timeout.
Cause più comuni:

• Esecuzione lenta di uno script PHP
• Query al database lente
• Carico elevato sul server

Come risolvere:

1. Aumenta i timeout nella configurazione del sito (nel blocco server o location):

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

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

pm.max_children = 50          # aumenta secondo necessità
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
request_terminate_timeout = 300

3. Riavvia i servizi:

sudo systemctl restart php-fpm
sudo systemctl reload nginx

4. Se il problema riguarda uno script specifico — ottimizza le query al DB o aggiungi il caching per le pagine pesanti.

413 Request Entity Too Large

Cosa significa: Il client sta cercando di caricare un file più grande del limite consentito da NGINX (1 MB per impostazione predefinita).
Cause comuni: caricamento di file di grandi dimensioni (foto, video, backup, archivi).

Come risolvere:

1. Aumenta il limite nella configurazione del sito (o in /etc/nginx/nginx.conf, nel blocco http):

client_max_body_size 64M;  # o 128M, 512M, 1G, ecc.

2. Ricarica NGINX:

sudo nginx -t && sudo systemctl reload nginx

3. Aumenta anche i limiti PHP nel php.ini (/etc/php/8.1/fpm/php.ini):

upload_max_filesize = 64M
post_max_size = 64M

Riavvia PHP-FPM:

sudo systemctl restart php-fpm

Come ricaricare NGINX correttamente

• Verifica sempre la configurazione prima di tutto:

sudo nginx -t

• Ricaricamento senza interruzioni (graceful reload):

sudo systemctl reload nginx

oppure

sudo nginx -s reload

• Riavvio completo (solo se il reload non risolve):

sudo systemctl restart nginx

Note utili

• Fai sempre un backup delle configurazioni prima di apportare modifiche: sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
• Dopo ogni modifica, controlla i log: /var/log/nginx/error.log e /var/log/nginx/access.log