Schermata bianca: come si debugga un sito che non dice niente

Prima cosa da fare: guarda il log, non il browser

Sito giù, schermata bianca, niente messaggio. La verifica più veloce non è ricaricare la pagina: è aprire il log degli errori PHP, che nella maggior parte dei casi contiene già la riga che ti serve, anche se sullo schermo non compare nulla.

Su Ubuntu 24.04 con Nginx e PHP-FPM il comando è:

sudo tail -n 50 /var/log/php8.3-fpm.log

(il nome del file cambia con la versione di PHP installata: su PHP 8.1 è /var/log/php8.1-fpm.log). Se il pacchetto non ha un log dedicato attivo, il percorso di default della direttiva error_log di PHP-FPM è Path to error log file, con valore di default #INSTALL_PREFIX#/log/php-fpm.log, come documentato nel manuale ufficiale di PHP. Su un'istanza cPanel guarda invece /usr/local/cpanel/logs/error_log o, per il singolo dominio, la voce "Errori" nel pannello (cPanel → Metrica → Errori). Su Plesk il file è sotto /var/www/vhosts/system/<dominio>/logs/error_log.

Su questi sistemi condivisi, se non vedi nulla neanche lì, il problema potrebbe essere a monte: lo spieghiamo più avanti.

Cosa significa l'errore

La pagina bianca è quasi sempre un fatal error PHP: il motore si è fermato prima di generare qualunque output, e di default PHP in produzione ha display_errors disattivato, quindi non stampa niente. Il visitatore vede il vuoto, tu vedi il vuoto, ma da qualche parte un log sta scrivendo la causa.

Accendere i log senza esporli ai visitatori

Se il sito è WordPress e riesci ad arrivare a wp-config.php via FTP, SSH o file manager, aggiungi prima della riga /* That's all, stop editing! */ queste righe:

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

Con questa configurazione il codice inserito nel file wp-config.php registrerà tutti gli errori, gli avvisi e i warning in un file chiamato debug.log nella directory wp-content, nascondendoli allo stesso tempo in modo che non interrompano la generazione della pagina, come indica la documentazione ufficiale sviluppatori di WordPress. Il file finisce in wp-content/debug.log all'interno del filesystem del sito; se vuoi spostarlo fuori dalla document root (consigliato, perché quel percorso è pubblico e prevedibile) puoi sostituire true con un path assoluto: puoi impostarlo a un percorso di file valido per salvare il file altrove.

Attenzione: un file debug.log dimenticato attivo in produzione è un problema di sicurezza, non solo di pulizia. Chi scansiona siti WordPress sa che il file di log di debug viene creato con un nome file noto, debug.log, e di solito si trova nella directory /wp-content/ accessibile pubblicamente, e un attaccante può scaricarlo per leggere percorsi, credenziali parziali o query SQL. Disattiva WP_DEBUG appena hai finito.

Ricarica la pagina che dà il bianco, poi:

tail -n 50 wp-content/debug.log

La riga che conta è quella che inizia con PHP Fatal error: seguita dal nome della funzione o della classe mancante e, tra parentesi, il file e la riga esatta dove è avvenuto l'errore. È quella riga che ti dice se la causa è un plugin, il tema o il core.

Le cause più frequenti, in ordine

1. Un plugin aggiornato o incompatibile. È la causa più comune. Nel log vedrai il percorso dentro wp-content/plugins/<nome-plugin>/.

2. Il tema, o un child theme con codice nel functions.php. Il percorso nel log sarà sotto wp-content/themes/.

3. Limite di memoria PHP esaurito. Il log riporta la dicitura "Allowed memory size of ... bytes exhausted".

4. Versione di PHP non compatibile con un plugin o il core, tipico subito dopo un aggiornamento di PHP fatto dal provider.

5. File core corrotti o caricamento incompleto (upload FTP interrotto, aggiornamento automatico fallito a metà).

Come isolare la causa quando non entri nemmeno nel pannello

Se il wp-admin è bianco anche lui, non puoi disattivare i plugin da interfaccia. Due strade, a seconda di cosa hai a disposizione.

Da filesystem (FTP/SSH). Rinomina la cartella dei plugin:

mv wp-content/plugins wp-content/plugins-disabled
mkdir wp-content/plugins

WordPress non trova più i plugin attivi e li considera tutti disattivati senza cancellare nulla; la pagina torna visibile se la causa era lì. Poi rinomini la cartella originale al contrario e sposti dentro, uno alla volta, i plugin disattivati, ricaricando il sito a ogni spostamento, finché non torna bianco: quello appena rimesso è il colpevole. Stesso principio per il tema: rinomina wp-content/themes/<nome-tema> in qualcos'altro, WordPress ripiega automaticamente su un tema di default se ne trova uno installato (es. Twenty Twenty-Four).

Da database, se non hai accesso FTP ma hai phpMyAdmin o un client da riga di comando:

mysql -u <utente> -p <nome_database> -e "UPDATE wp_options SET option_value = 'a:0:{}' WHERE option_name = 'active_plugins';"

Questo comando svuota l'elenco dei plugin attivi senza toccare i file: equivale a disattivarli tutti dal pannello. Da lì puoi riattivarli uno alla volta da wp-admin, oppure agire di nuovo sulla riga active_plugins per reinserirli a mano.

Se il bianco arriva dopo un aggiornamento

Se il sito funzionava e si è rotto subito dopo un aggiornamento (plugin, tema, PHP, o update automatico di WordPress), il log ti dirà quasi sempre il nome della funzione che non esiste più o che si aspetta un parametro diverso: è il sintomo tipico di un cambio di versione PHP che rompe codice vecchio, oppure di un plugin che richiede una versione minima di WordPress più recente di quella installata. Prima di disattivare tutto, controlla la versione di PHP in uso (php -v da SSH, oppure la pagina Strumenti → Salute del sito in WordPress) e confrontala con quella richiesta dal plugin o dal tema nel suo changelog.

Quando il problema non è tuo

Se il log PHP non mostra nessun errore applicativo ma il sito resta bianco o va in timeout, il sospetto si sposta sul livello sotto: PHP-FPM che non risponde, limiti di risorse del piano hosting (memoria, processi), o un problema sul nodo del provider. In questo caso apri un ticket con il tuo hosting allegando: l'orario esatto (con fuso) in cui si è verificato il bianco, l'URL della pagina interessata, l'output di tail del log PHP-FPM e, se disponibile, l'ID del ticket o del dominio nel pannello. Senza questi dati l'assistenza parte da zero e il tempo di risposta si allunga.

Come verificare che è risolto

Dopo l'intervento, ricarica la pagina che dava il bianco e controlla che il log non registri nuove righe di errore nello stesso punto. Infine disattiva WP_DEBUG e, se l'avevi spostato, rimuovi il file di log esterno: lasciarlo attivo in produzione serve solo a riempire il disco e a esporre informazioni che non devono essere pubbliche.