500 Internal Server Error: cause, log e differenze dal 502

Perché 500 ti dice così poco

L'RFC 9110 definisce 500 come una condizione imprevista che ha impedito al server di soddisfare la richiesta. È deliberatamente ampio. Qualsiasi cosa l'applicazione non abbia previsto, da un riferimento nullo a una connessione al database fallita a un file di configurazione che non riesce ad analizzare, finisce sotto lo stesso numero.

La vaghezza è anche una caratteristica di sicurezza. Una pagina 500 non dovrebbe mai far trapelare stack trace, percorsi di file, frammenti SQL o versioni di librerie al pubblico, perché sono esattamente i dettagli che un aggressore vuole. Quindi il codice resta generico nella risposta, e il dettaglio va in un log che solo tu puoi leggere. Questo compromesso è corretto, e rende una singola conoscenza più utile di ogni altra: dove vivono i tuoi log.

500 contro 502, 503 e 504

Tutti e quattro sono errori del server, ma sono prodotti da componenti diversi e indicano problemi diversi. Capire questo bene fa risparmiare la maggior parte del tempo di debug.

• 500 viene dall'applicazione stessa. Qualcosa è girato e ha lanciato un'eccezione. Il log dell'applicazione ha uno stack trace.
• 502 viene da un proxy davanti all'applicazione, che ha ricevuto una risposta non valida o una connessione chiusa dal backend. Il backend spesso non registra nulla, perché non ha mai finito la richiesta. Vedi la guida al 502.
• 503 è un rifiuto, non un crash. Il server è sovraccarico o in manutenzione e sta declinando il lavoro di proposito, di solito con Retry-After.
• 504 è un timeout. Il backend era raggiungibile ma non ha risposto entro il limite del proxy. La richiesta spesso sta ancora girando dietro le quinte.

Una scorciatoia diretta: 500 significa che il tuo codice si è rotto, 502 significa che il tuo backend è morto o si comporta male, 503 significa che il tuo server sta dicendo di no apposta, 504 significa che il tuo backend è troppo lento. L'intera famiglia è confrontata nella panoramica 5xx.

Cosa causa un 500

• Eccezioni non gestite nel codice dell'applicazione. La categoria singola più grande. Un valore nullo, una conversione di tipo fallita, un indice di array fuori intervallo, una divisione per zero su un percorso che nessuno ha testato.
• Fallimenti del database. Pool di connessioni esaurito, credenziali ruotate, il database si è riavviato, una query che va in deadlock o in timeout.
• Dipendenze mancanti o rotte dopo un deploy. Un pacchetto che non si è installato, un file che la build non ha copiato, una variabile d'ambiente che esiste in staging e non in produzione.
• Errori di sintassi nella configurazione. Su Apache, una singola direttiva non valida in un file .htaccess produce 500 per ogni richiesta sotto quella directory.
• Permessi e proprietà dei file. L'applicazione non riesce a leggere un file di configurazione o a scrivere in una directory di cache, sessione o upload.
• Limiti di risorse. Un limite di memoria, un limite di tempo di esecuzione o un disco pieno. Questi tipicamente producono 500 intermittenti che seguono il traffico.
• Fallimenti di API di terze parti che il codice chiama senza un fallback, così un'interruzione remota diventa la tua pagina di errore.

Come diagnosticare un 500

1. Conferma il codice e chi lo ha prodotto. Una pagina di errore personalizzata può nascondere lo stato reale:

   curl -sS -o /dev/null -D - https://example.com/failing-page

   Controlla la riga di stato e qualsiasi intestazione Server o della CDN. Se l'errore è firmato da una rete edge e l'origine risponde 200, non stai guardando affatto un 500 della tua applicazione.
2. Apri prima il log dell'applicazione. È lì che si trova lo stack trace. I log del framework, il flusso di log della piattaforma o lo stdout del container, qualunque usi il tuo stack, e fai corrispondere per timestamp e percorso della richiesta.
3. Poi il log degli errori del server web. error_log di Apache, error.log di nginx, o il Windows Event Log per IIS. Se l'applicazione non ha mai registrato nulla, il guasto è avvenuto prima che il tuo codice girasse, il che indica la configurazione o il runtime.
4. Riproducilo deliberatamente. Stabilisci se il 500 riguarda un URL, un metodo HTTP, un utente o tutti. Un 500 solo su POST di solito significa gestione dei moduli o un percorso di scrittura. Un 500 per un solo utente di solito significa i suoi dati.
5. Attiva gli errori dettagliati in un ambiente non pubblico. Mai in produzione. Riproduci in staging con output di errore completo, il che trasforma un 500 generico in una riga di codice specifica.
6. Controlla cosa è cambiato. L'ultimo deploy, un push di configurazione, un rinnovo del certificato, un aggiornamento di dipendenza o una migrazione del database. Se il sito andava bene un'ora fa, la risposta è quasi sempre nell'ultima modifica.
7. Controlla le risorse dell'host. Spazio su disco, memoria e conteggio delle connessioni. Un disco che si è riempito di log produce 500 che sembrano completamente scollegati dal codice.

I 500 che restituisce solo una pagina

La maggior parte dei 500 non mette giù l'intero sito. Una rotta, un modulo o una regione si rompe mentre la homepage continua a caricarsi, così nulla sembra sbagliato dall'esterno e gli errori emergono giorni dopo come iscrizioni perse. Un controllo HTTP pianificato sulle pagine che contano, non solo la homepage, confronta il codice restituito con quello atteso e avvisa nel momento in cui una rotta inizia a rispondere 500. Gli avvisi possono arrivare via email, SMS, chiamata vocale, Slack, Telegram e altro, così un guasto notturno raggiunge chi è di turno invece di aspettare il mattino. HostTracker monitora siti web dal 2004.