Un errore 500 Internal Server Error significa che l’applicazione sul server ha incontrato un problema che non è riuscita a gestire mentre costruiva la risposta. A differenza della maggior parte degli altri errori, non dice cosa è andato storto. È il modo in cui il server dice “qualcosa si è rotto, e al visitatore non dico cosa”.
Il vero messaggio di errore però esiste: si trova in un log. Questa guida ti mostra dove trovarlo, le cause dietro la maggior parte degli errori 500 e come assicurarti di essere il primo a saperlo quando ne compare uno.
Cosa ti dice un errore 500
Un 500 arriva dall’applicazione stessa o dal web server che la esegue. Significa che la richiesta ha raggiunto il tuo codice e il codice ha fallito: un’eccezione che nessuno ha intercettato, un errore fatale, una configurazione che il server non è riuscito a leggere. È questo a distinguerlo dagli errori di gateway, in cui il problema sta tra due server:
500 Internal Server Error: l’applicazione ha fallito mentre gestiva la richiesta.
502 Bad Gateway: un proxy ha ricevuto una risposta non valida dall’applicazione. Leggi la nostra guida al 502.
503 Service Unavailable: il servizio è sovraccarico o in manutenzione. Leggi la nostra guida al 503.
504 Gateway Timeout: l’applicazione è stata troppo lenta a rispondere. Leggi la nostra guida al 504.
Un 500 su una sola pagina di solito indica un bug nel codice di quella pagina. Un 500 su tutte le pagine di solito significa che si è rotto qualcosa di condiviso: la configurazione, la connessione al database, un file caricato dall’intera applicazione.
Parti da cosa è cambiato
La maggior parte degli errori 500 compare subito dopo una modifica. Prima ancora di leggere un log, chiediti cosa è successo nell’ultima ora:
Un deploy o un merge sul branch principale
L’aggiornamento di un plugin, di un tema, di un framework o del linguaggio
Una modifica a un file di configurazione, a .htaccess o alle variabili d’ambiente
Una password o una chiave API ruotata
Un server con il disco pieno o con i permessi modificati
Se le tempistiche coincidono, annullare la modifica è spesso il modo più rapido per rimettere online il sito. La causa la cerchi dopo, senza i clienti a guardare.
Trova il vero messaggio di errore
La pagina di errore 500 è generica, il log è specifico. Dove guardare dipende dallo stack:
# nginx and Apache
tail -n 50 /var/log/nginx/error.log
tail -n 50 /var/log/apache2/error.log
# PHP-FPM
tail -n 50 /var/log/php8.3-fpm.log
# Applications run by systemd
journalctl -u myapp –since “15 min ago”
# Docker
docker logs –since 15m myapp
Cerca il timestamp della richiesta fallita. La voce accanto di solito indica il file, la riga e il motivo: una funzione non definita, una classe mancante, un database che ha rifiutato la password.
Su WordPress, attiva il log di debug in wp-config.php. Scrive gli errori in wp-content/debug.log senza mostrarli ai visitatori:
define( ‘WP_DEBUG’, true );
define( ‘WP_DEBUG_LOG’, true );
define( ‘WP_DEBUG_DISPLAY’, false );
Disattivalo quando hai finito, perché il log può diventare molto grande e contenere dati sensibili.
Cause comuni e come risolverle
Un errore nel codice
Un’eccezione non gestita o un errore fatale nel codice che costruisce la pagina. Il log indica il file e la riga. I fattori scatenanti tipici sono una funzione chiamata con dati che non si aspettava, un valore inaspettatamente vuoto e codice che funziona sul computer dello sviluppatore ma richiede un’estensione PHP o una versione di una libreria che il server non ha. Correggi il codice o torna all’ultima versione funzionante.
L’aggiornamento di un plugin o di un tema
Su WordPress e sugli altri CMS, l’aggiornamento di un plugin o di un tema è la causa più frequente. Il log indica la cartella del plugin. Se non riesci ad accedere al pannello di amministrazione, rinomina quella cartella via SSH o SFTP per disattivarlo:
mv wp-content/plugins/some-plugin wp-content/plugins/some-plugin.disabled
Il sito torna online senza quel plugin. A quel punto aggiornalo di nuovo, sostituiscilo o contatta il suo sviluppatore con l’errore trovato nel log.
Un file .htaccess danneggiato
Su Apache basta una riga sbagliata in .htaccess per mandare l’intero sito in errore 500. Il log degli errori riporta Invalid command o indica la direttiva che non ha capito. Rinomina il file per fare una prova, poi ripristina le righe una alla volta. Su WordPress, salvare le impostazioni dei permalink ne scrive uno nuovo.
PHP senza memoria
Allowed memory size of 134217728 bytes exhausted significa che una richiesta ha avuto bisogno di più memoria di quanta ne consenta memory_limit. Alzare il limite può aiutare, ma una richiesta che richiede centinaia di megabyte di solito carica troppi dati in una volta sola. Scopri cosa carica prima di dargliene di più.
Permessi e proprietà dei file
Dopo un deploy, un ripristino o una copia manuale, i file possono finire di proprietà dell’utente sbagliato. Il web server allora non riesce a leggere il codice né a scrivere nelle cartelle di cache e di upload, e il log riporta Permission denied. Riassegna la proprietà all’utente con cui girano il web server o PHP. Di norma le directory richiedono 755 e i file 644; non risolvere mai il problema con 777.
Un disco pieno
Quando il disco è pieno, le applicazioni non riescono a scrivere sessioni, cache, upload o log, e falliscono in modi che finiscono con un 500. Controlla lo spazio e gli inode:
df -h
df -i
I soliti colpevoli sono vecchi log, backup e cache. Il monitoraggio dei server con un avviso sul disco all’80 o al 90 percento se ne accorge giorni prima che il sito si blocchi.
Errori di connessione al database
Una password cambiata, un server di database fermo o un limite di connessioni raggiunto. L’applicazione non riesce a caricare nulla e fallisce su ogni pagina. Il log indica l’errore del database. Verifica che il database sia in esecuzione, che le credenziali nella configurazione siano aggiornate e quante connessioni sono aperte rispetto al limite.
Il 500 che restituisce 200
Non tutte le pagine rotte lo dicono. Alcune applicazioni intercettano l’errore e mostrano una pagina cortese con “Qualcosa è andato storto” e stato 200, e un CMS può mostrare un elenco prodotti vuoto senza lamentarsi. Per un monitor che guarda solo il codice di stato, sembra tutto a posto.
Controlla anche il contenuto. Un monitor di uptime può richiedere che una pagina contenga una parola sempre presente quando funziona, come il nome del prodotto o “Aggiungi al carrello”, e considerare la sua assenza un errore. La nostra checklist di cosa monitorare elenca le pagine che meritano questo tipo di controllo.
Come il monitoraggio intercetta gli errori 500
Un 500 dopo un deploy può restare inosservato per ore se colpisce una sola pagina. Il checkout si blocca, la homepage funziona ancora e il team lo scopre dall’email di un cliente o da un calo delle vendite.
Controlla le pagine che portano fatturato. Aggiungi monitor di uptime per checkout, login, registrazione e API, non solo per la homepage, con controlli sul contenuto dove un 200 può nascondere un errore.
Conferma prima di avvisare. Uptimecheck esegue controlli fino a ogni minuto da Stoccolma, Londra e New York e conferma ogni errore da una seconda località, così una singola richiesta fallita non fa scattare l’allarme a nessuno.
Guarda cosa si è rotto. L’incidente include la risposta fallita, con il codice di stato e la pagina di errore, e uno screenshot di ciò che ha visto il visitatore.
Testa i flussi completi. Un login o un checkout che fallisce al terzo passaggio restituisce 200 al primo. I flussi in più passaggi percorrono tutti i passaggi e ti dicono quale è fallito.
Checklist per l’errore 500
Chiediti cosa è cambiato nell’ultima ora e annulla la modifica se le tempistiche coincidono.
Trova nel log degli errori il timestamp della richiesta fallita.
Leggi l’errore: file, riga e motivo.
Escludi le cause più comuni: un plugin, .htaccess, memoria, permessi, disco, database.
Risolvi la causa, poi rimuovi le impostazioni di debug che hai attivato.
Monitora le pagine chiave ogni minuto, con controlli sul contenuto dove un 200 può nascondere un errore.
Testa login e checkout come flussi, non come singole pagine.