Capire gli errori di WordPress e fare il debug del sito

Schermata bianca, «Si è verificato un errore critico sul tuo sito web.», errore 500 o connessione al database impossibile: dietro ogni messaggio di WordPress c’è una causa precisa, quasi sempre scritta da qualche parte in un log. Questa guida spiega come leggere gli errori più comuni, usare la modalità di recupero, attivare il debug senza esporre il sito e quali strumenti permettono di trovare il colpevole in pochi minuti.

La prima mossa: trovare il messaggio reale

Il messaggio mostrato al visitatore è volutamente vago: non deve rivelare i percorsi del server. L’errore vero si trova, dal posto più semplice al più complesso:

1. nell’email della modalità di recupero, inviata all’indirizzo email di amministrazione quando si verifica un errore fatale;
2. nei log degli errori PHP dell’hosting (area clienti, cPanel, Plesk);
3. nel log di debug di WordPress, una volta attivato;
4. nella console del browser per gli errori JavaScript (editor a blocchi bloccato, un pulsante che non risponde più).

Prima di cercare, chiediti che cosa è cambiato: l’aggiornamento di un plugin, una nuova versione di PHP sull’hosting, una modifica al tema. Nove volte su dieci la causa è lì.

Gli errori di WordPress più frequenti

Cosa vedi	Causa probabile	Prima azione
Pagina bianca	Errore PHP fatale, visualizzazione degli errori disattivata	Leggere il log degli errori, disattivare l’ultimo plugin modificato
«Si è verificato un errore critico sul tuo sito web.»	Errore fatale in un plugin o nel tema	Seguire il link dell’email di recupero
Errore 500	.htaccess non valido, limite del server, errore PHP	Rinominare .htaccess, leggere il log del server
404 su tutte le pagine tranne la home	Regole di riscrittura perse	Impostazioni, Permalink, Salva le modifiche
«Errore nello stabilire una connessione al database»	Credenziali errate in wp-config.php, server MySQL fermo	Verificare le credenziali, contattare l’hosting
«Allowed memory size… exhausted»	Memoria PHP insufficiente o plugin troppo esigente	Aumentare WP_MEMORY_LIMIT, cercare la perdita
«Momentaneamente non disponibile per manutenzione. Riprova fra un minuto.»	Aggiornamento interrotto, file .maintenance rimasto	Eliminare .maintenance, rilanciare l’aggiornamento
Troppi reindirizzamenti	Indirizzo del sito in HTTP dietro un proxy in HTTPS	Verificare siteurl, home e il rilevamento di HTTPS

Memoria esaurita

Per impostazione predefinita WordPress richiede 40 MB di memoria (64 MB in multisito) per il sito pubblico e fino a 256 MB nella bacheca, senza poter superare il limite fissato dall’hosting. Puoi alzare il primo valore in wp-config.php con define( 'WP_MEMORY_LIMIT', '256M' );. Se l’errore ritorna anche con più memoria, un plugin è in loop: aumentarla ancora rimanda soltanto il guasto.

Modalità manutenzione bloccata

Durante un aggiornamento, WordPress crea un file .maintenance nella cartella principale. Dopo dieci minuti lo ignora da solo; se il messaggio persiste, elimina il file, poi svuota la cache delle pagine, che potrebbe aver memorizzato la schermata di manutenzione. Rilancia quindi l’aggiornamento interrotto, perché il plugin interessato potrebbe essere incompleto.

La modalità di recupero dopo un errore critico

Da WordPress 5.2, un errore fatale attiva la modalità di recupero: WordPress invia all’indirizzo di amministrazione un’email che indica il plugin o il tema responsabile e contiene un link di accesso speciale. Il link apre la bacheca con il componente difettoso sospeso solo per te, il tempo di disattivarlo o aggiornarlo. Il link è valido solo per un tempo limitato.

L’email non arriva? Forse l’indirizzo di amministrazione non è aggiornato, oppure il sito non invia email. Puoi definire un altro indirizzo con la costante RECOVERY_MODE_EMAIL, oppure disattivare il plugin senza passare dalla bacheca:

# Senza caricare i plugin né il tema che causano l’errore
wp plugin list --status=active --skip-plugins --skip-themes
wp plugin deactivate nome-plugin --skip-plugins --skip-themes

# Senza WP-CLI: rinominare la cartella del plugin via SFTP
# wp-content/plugins/nome-plugin  diventa  nome-plugin.off

Attivare il debug senza esporre il sito

La modalità di debug si imposta in wp-config.php, prima della riga «That's all, stop editing! Happy publishing.» (è tutto, smetti di modificare). Su un sito online bisogna registrare gli errori senza mai mostrarli, e scrivere il log fuori dalla cartella pubblica:

define( 'WP_DEBUG', true );
// Log fuori dalla cartella pubblica (adatta il percorso al tuo hosting)
define( 'WP_DEBUG_LOG', '/home/account/logs/wp-errors.log' );
// Mai mostrare errori ai visitatori
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
// Solo per un errore JavaScript del core: script non minificati
// define( 'SCRIPT_DEBUG', true );

Con WP_DEBUG_LOG impostato su true, il log viene scritto in wp-content/debug.log, un indirizzo che tutti conoscono e che i bot provano di continuo. Questo file contiene percorsi del server, nomi di plugin e talvolta query SQL o indirizzi email: non lasciarlo mai accessibile pubblicamente in produzione. Meglio un percorso fuori dalla cartella pubblica; blocca l’accesso al file a livello di server e, una volta trovato il problema, rimetti WP_DEBUG su false ed elimina il log. Il nostro articolo sui file sensibili esposti mostra come verificarlo, e la nostra guida a wp-config.php descrive le altre impostazioni.

Il metodo per isolare il colpevole

Per isolare senza rompere il sito ai visitatori, il plugin Health Check & Troubleshooting offre una «Modalità Diagnostica» che disattiva i plugin e cambia tema solo per la tua sessione. Su un ambiente di staging puoi invece disattivare tutto e riattivare un elemento alla volta.

Gli strumenti di diagnosi

• Salute del sito (Strumenti): la scheda Stato segnala i problemi noti (PHP datato, eventi pianificati in ritardo, richieste esterne bloccate); la scheda Informazioni riporta la configurazione completa, da copiare per una richiesta di assistenza.
• Query Monitor: plugin gratuito che mostra, ai soli amministratori, gli errori PHP della pagina, le query SQL lente o duplicate, le chiamate HTTP e il componente responsabile di ciascuna. Da disattivare a diagnosi conclusa.
• WP-CLI: wp doctor non è incluso di default, ma wp core verify-checksums, wp plugin list e --skip-plugins bastano nella maggior parte dei casi.
• Console del browser (F12): errori JavaScript e richieste fallite (403, 500) quando l’editor o un modulo non risponde più.

How Do I Debug WordPress? Enable Logs, Find Errors, Recover Your SiteCliccando, il video viene caricato da youtube-nocookie.com (YouTube, Google). Prima del tuo clic non viene caricato nulla.

Gli errori legati alla versione di PHP

WordPress 7 richiede almeno PHP 7.4 e consiglia PHP 8.3 o successivo. Il passaggio a una nuova versione di PHP è la causa più frequente degli errori critici «senza aver toccato nulla»: l’hosting cambia versione e un plugin datato usa una funzione rimossa. L’avviso «Deprecated» di oggi diventa l’errore fatale della versione successiva.

• Prima di cambiare versione, fai una prova su un ambiente di staging con il log di debug attivo e leggi gli avvisi.
• Se il sito va giù dopo il cambio, torna alla versione precedente dall’area clienti dell’hosting, il tempo di aggiornare o sostituire il plugin responsabile.
• Non restare su una versione a fine vita per un solo plugin: sostituiscilo. Il calendario è nel nostro articolo sulle versioni di PHP a fine vita.

Sapere che cosa è cambiato prima del guasto

Alla domanda «che cosa è cambiato?» si risponde più facilmente con una traccia. WP Masquerade Pro tiene un registro delle attività degli amministratori (plugin attivati, disattivati o aggiornati, impostazioni modificate, con autore e ora), segnala con il controllo di integrità un file del core modificato e ti invia avvisi via email. Non è uno strumento di debug: non legge gli errori PHP. Ma spesso risponde alla prima domanda della diagnosi. La versione gratuita, dal canto suo, rimuove le tracce di WordPress dal codice delle pagine, il che non sostituisce la protezione del file debug.log.

Domande frequenti

Come risolvere «Si è verificato un errore critico sul tuo sito web.»?

Apri l’email di recupero inviata all’indirizzo di amministrazione, segui il link e disattiva o aggiorna il componente indicato. Senza email, disattiva il plugin con WP-CLI usando --skip-plugins o rinominando la sua cartella via SFTP, poi leggi il log degli errori.

Dove si trova il file debug.log?

Di default in wp-content/debug.log quando WP_DEBUG_LOG vale true. Meglio indicare un percorso fuori dalla cartella pubblica ed eliminare il file a diagnosi conclusa.

Si può lasciare WP_DEBUG attivo in produzione?

Solo con la visualizzazione disattivata e un log fuori dalla cartella pubblica, per la durata della diagnosi. Normalmente lascialo su false: il log cresce e un file dimenticato diventa una fuga di informazioni.

Perché il mio sito mostra un errore 500 senza alcun messaggio?

Spesso l’errore viene dal server ancora prima di WordPress: una regola non valida in .htaccess, un limite di risorse, la versione di PHP. Rinomina .htaccess, leggi il log degli errori del server nell’area clienti dell’hosting e contatta l’assistenza se il log è vuoto.

Fonti

• WordPress Developer: il debug in WordPress (link esterno, si apre in una nuova scheda)
• Make WordPress Core: la modalità di recupero dagli errori fatali in 5.2 (link esterno, si apre in una nuova scheda)
• WordPress.org: requisiti (link esterno, si apre in una nuova scheda)
• WordPress.org: Query Monitor (link esterno, si apre in una nuova scheda)