Schermata bianca WordPress: trova il colpevole nel log

La schermata bianca WordPress indica spesso un errore PHP fatale, un plugin incompatibile, un tema difettoso o una memoria esaurita. Il modo più rapido per individuare la causa consiste nell’attivare temporaneamente il registro di debug e leggere il file wp-content/debug.log. Il messaggio registrato contiene generalmente il nome dell’estensione, del tema o del file PHP che ha provocato il blocco. La procedura funziona anche quando il sito non permette più di accedere alla bacheca, usando FTP o il pannello File Manager dell’hosting.

Come attivare il registro di debug di WordPress

Il registro di debug di WordPress si attiva modificando il file wp-config.php, normalmente presente nella cartella principale dell’installazione, insieme a wp-admin, wp-content e wp-includes. Prima di apportare modifiche, scarica una copia del file originale: un errore di sintassi in wp-config.php può rendere il sito completamente irraggiungibile.

Apri wp-config.php con un editor di testo semplice e inserisci queste definizioni prima della riga /* That's all, stop editing! Happy publishing. */:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

WP_DEBUG abilita la modalità di debug, mentre WP_DEBUG_LOG ordina a WordPress di registrare gli errori nel file wp-content/debug.log. WP_DEBUG_DISPLAY impedisce di mostrare i dettagli tecnici nelle pagine pubbliche, una scelta importante perché i messaggi PHP possono rivelare percorsi dei file, nomi utente o informazioni sulla configurazione del server.

Se nel file sono già presenti queste costanti, modifica i valori esistenti invece di aggiungere nuove righe. Definire due volte la stessa costante può generare avvisi e rendere meno chiaro quale impostazione venga applicata. La documentazione ufficiale di WordPress sul debug indica inoltre di usare questa modalità per individuare problemi durante lo sviluppo, non come impostazione permanente su un sito pubblico.

Dove trovare e leggere wp-content/debug.log

Dopo aver salvato wp-config.php, riproduci l’errore aprendo la pagina che mostra la schermata bianca WordPress. Accedi quindi ai file del sito tramite FTP, SFTP o File Manager dell’hosting e apri:

/wp-content/debug.log

Il file potrebbe non esistere prima che WordPress registri il primo errore. Se non viene creato, controlla che WP_DEBUG sia impostato su true, che WP_DEBUG_LOG sia attivo e che la cartella wp-content sia scrivibile dall’utente utilizzato dal server web.

Leggi soprattutto le righe più recenti, perché spesso corrispondono all’ultimo tentativo di caricamento della pagina. Un errore utile contiene generalmente:

  • il tipo di errore, come Fatal error, Parse error o Allowed memory size exhausted;
  • il percorso del file PHP coinvolto;
  • il numero della riga in cui WordPress ha rilevato il problema;
  • il nome del plugin o del tema responsabile;
  • la data e l’ora dell’evento.

Un messaggio come Call to undefined function segnala di solito una funzione mancante o un’incompatibilità tra componenti. La dicitura Allowed memory size exhausted indica invece che lo script ha superato la memoria PHP disponibile, mentre Cannot redeclare function può derivare da codice duplicato o da due estensioni che caricano la stessa funzione.

Il file debug.log può contenere informazioni riservate e non deve essere lasciato accessibile pubblicamente più a lungo del necessario. Evita di incollare online il registro completo senza rimuovere percorsi, indirizzi, chiavi, nomi utente e altri dati identificativi.

Come collegare l’errore a plugin, tema o versione PHP

Il percorso del file riportato nel registro permette spesso di riconoscere immediatamente il componente difettoso. Un percorso che contiene wp-content/plugins/nome-plugin/ punta al plugin indicato, mentre una directory sotto wp-content/themes/nome-tema/ coinvolge il tema attivo o un suo componente.

Quando l’amministrazione di WordPress è ancora raggiungibile, disattiva prima l’estensione indicata dal log da Plugin > Plugin installati. Svuota eventuali cache del plugin, del server o della rete di distribuzione dei contenuti, quindi ricarica la pagina che mostrava l’errore. Se la schermata bianca WordPress scompare, aggiorna il plugin alla versione disponibile compatibile con la tua versione di WordPress e con PHP.

Se non puoi entrare nella bacheca, disattiva temporaneamente tutti i plugin rinominando via FTP la cartella:

/wp-content/plugins

Per esempio, puoi cambiarla in:

/wp-content/plugins.disattivati

WordPress non troverà più la directory standard e disattiverà i plugin. Se il sito torna online, ripristina il nome originale e rinomina una alla volta le cartelle dei singoli plugin, verificando ogni volta il caricamento del sito. Questa procedura consente di isolare il componente senza cancellare impostazioni o file.

Se il log indica il tema attivo, rinomina la cartella del tema in wp-content/themes. WordPress può passare a un tema predefinito installato, ma il ripristino automatico non è garantito se non è presente almeno un tema compatibile. Non eliminare il tema: rinominarlo permette di tornare rapidamente alla configurazione precedente dopo aver risolto il problema.

Controlla anche la versione PHP impostata nel pannello dell’hosting. Un plugin o un tema può non essere compatibile con una versione PHP più recente, ma il registro da solo non autorizza a stabilire quale versione sia corretta. Verifica i requisiti dichiarati dal produttore, la versione di WordPress installata e l’eventuale changelog dell’estensione prima di cambiare PHP su un sito in produzione.

Cosa fare quando debug.log non basta

Se debug.log è vuoto o non viene generato, controlla il registro degli errori PHP del server. Il provider può chiamarlo PHP error log, Error log, Registro errori o inserirlo nella sezione dedicata a PHP del pannello di hosting. Gli errori avvenuti prima del caricamento completo di WordPress, inclusi alcuni errori di sintassi, possono finire soltanto nel registro del server.

Verifica anche il limite di memoria PHP. Il messaggio Allowed memory size exhausted richiede un intervento sul limite memory_limit, ma il valore disponibile dipende dal piano hosting e dalla configurazione del server. Un aumento della memoria può attenuare il sintomo senza correggere il plugin o il tema che consuma risorse in modo anomalo.

WordPress 5.2 e versioni successive possono inviare un’email di Modalità di recupero quando rilevano un errore PHP critico. Il collegamento presente nel messaggio consente all’amministratore di accedere temporaneamente alla bacheca e disattivare il componente problematico. Se l’email non arriva, controlla la posta indesiderata e verifica l’indirizzo dell’amministratore, ma considera comunque il log e il registro PHP del server come fonti più affidabili.

Dopo aver identificato e risolto la causa, rimuovi o disattiva le righe di debug da wp-config.php:

define( 'WP_DEBUG', false );
define( 'WP_DEBUG_LOG', false );
define( 'WP_DEBUG_DISPLAY', false );

Se avevi aggiunto anche @ini_set( 'display_errors', 0 );, puoi lasciarlo per impedire la visualizzazione degli errori oppure rimuoverlo insieme alle altre impostazioni temporanee. Elimina inoltre wp-content/debug.log dopo averne conservato una copia sicura: un registro lasciato sul server può crescere nel tempo e diventare un rischio informativo.

La schermata bianca WordPress diventa molto più semplice da risolvere quando il registro viene letto prima di disattivare componenti a caso.

Potrebbe interessarti anche:

Altri articoli di questa serie:

PDF Strumenti PDF gratis Nel browser, senza upload Apri gli strumenti