Diagnosi errore 'White Screen of Death' WordPress

Il White Screen of Death (WSOD) è la classica schermata bianca senza alcun messaggio che terrorizza chiunque gestisca WordPress. In realtà è quasi sempre un fatal error PHP che viene nascosto dalle impostazioni di produzione. In questa guida ti mostriamo come usare WP Error Monitor per identificare la causa in pochi minuti.

Cosa significa WSOD

Tecnicamente la pagina bianca è la conseguenza di un'errore PHP con display_errors=Off: PHP termina l’esecuzione senza inviare output. WordPress 5.2+ ha introdotto la 'recovery modè che mostra un messaggio più utile, ma molte installazioni non lo vedono perchè l’errore avviene prima del bootstrap completo (es. errore in mu-plugin o in wp-config.php).

Cause più frequenti

In ordine di frequenza: 1) plugin appena aggiornato con incompatibilità PHP, 2) tema con errore di sintassi (es. dopo modifica functions.php), 3) memoria PHP esaurita (Allowed memory exhausted), 4) timeout massimo execution_time, 5) errori in file di traduzione corrotti, 6) database corrotto o connessione persa, 7) opcache corrotta dopo deploy.

Approccio WP Error Monitor

L’agent intercetta il fatal tramite register_shutdown_function() e invia subito un'evento di severità CRITICAL. Nella dashboard vedrai file, riga e messaggio anche se il browser mostra pagina vuota. Questo evita la procedura manuale di abilitare WP_DEBUG, rinominare la cartella plugins e attivarli uno alla volta.

Procedure di accesso d’emergenza

Quando wp-admin è inaccessibile per WSOD, hai bisogno di accedere via altri canali. Le tre vie principali: 1) SFTP per modificare file, 2) SSH per WP-CLI, 3) phpMyAdmin/Adminer per query DB. Tieni sempre pronto un'user emergenza in vault (password manager) e SSH key autorizzata. Plesk semplifica il flusso: dal pannello hosting accedi a File Manager senza credenziali separate e WP Toolkit ha un 'Maintenance Mode' per disattivare plugin in batch.

Prevenzione WSOD futuri

Per ridurre la probabilità di WSOD: 1) abilita staging WordPress (WP Toolkit lo fa con un click), 2) testa update plugin sempre su staging prima, 3) abilita 'Smart Updates' di WP Toolkit che fa diff visivo pre/post update, 4) configura WP Error Monitor per inviare alert su deprecation/warning prima che diventino fatal, 5) usa snapshot Plesk pre-update per rollback rapido. La combinazione di queste pratiche riduce gli incident WSOD del 80%.

Snapshot pre-update e rollback

La strategia anti-WSOD più efficace è avere snapshot automatici prima di ogni operazione rischiosa. Plesk Backup Manager crea snapshot incrementali ogni giorno; WP Toolkit aggiunge snapshot 'point-in-time' pre-update plugin/core. In caso di WSOD post-update, il rollback richiede 30-60 secondi. WP Error Monitor si integra con WP Toolkit per fare snapshot automatico prima di aggiornamento: hook pre_auto_update aziona la chiamata API Plesk. Se l’update genera fatal nei 15 minuti successivi, scatena rollback automatico. Così' anche durante update notturni non assistiti il sito torna online da solo.

Debugging del fatal con stack trace

Quando WP Error Monitor cattura un fatal causa WSOD, lo stack trace mostra l’esatta chain di chiamate. Esempio: 'Fatal: Call to undefined function wp_xxx() in /wp-content/plugins/foo/init.php:42' con stack trace foo->bootstrap->init->plugin_loader. Da lì capisci che il plugin foo chiama una funzione WP rimossa nella versione corrente: probabile plugin con codice obsoleto. La risoluzione e': identifica versione plugin, controlla changelog per breaking change, aggiorna o downgrade. WP Error Monitor mantiene un database di 'pattern noti' che suggerisce automaticamente le risoluzioni per fatal ricorrenti.

Lessons learned dai casi reali

Dai casi reali gestiti dal team G Tech, le tre lesson learned principali per gestire il WSOD sono: primo, avere sempre snapshot Plesk recenti riduce il tempo di rollback da ore a minuti; secondo, WP Error Monitor configurato con WPEM_CAPTURE_LEVEL aggressivo intercetta deprecation che preannunciano fatal entro 24-48h, dandoti finestra preventiva; terzo, il runbook scritto della procedura WSOD risparmia errori sotto stress (in incident reali capita di dimenticare passi banali per nervosismo, il runbook li ricorda).

Procedura passo-passo

1. Apri WP Error Monitor e filtra per il sito interessato negli ultimi 30 minuti.
2. Cerca un'evento di severità CRITICAL o severity ALERT.
3. Apri il dettaglio: prendi file, riga e messaggio.
4. Se il messaggio cita un plugin, vai in admin (se accessibile) e disattivalo, oppure rinomina la cartella via FTP.
5. Se cita il tema, attiva temporaneamente twentytwentyfour via riga di comando: wp theme activate twentytwentyfour.
6. Se cita 'Allowed memory sizè, alza memory_limit in wp-config.php (define('WP_MEMORY_LIMIT', '512M')).
7. Una volta ripristinato il sito, applica il fix definitivo e marca l’evento come risolto.
8. Verifica che ci sia un'utente emergenza nel password manager.
9. Configura Plesk Smart Updates per i plugin critici.

Errori comuni e come risolverli

• Recovery mode non funziona: Il link arriva via email all’admin: controlla la cartella spam e che SMTP del sito sia configurato.
• Errore in mu-plugin: Le must-use non si disattivano dal pannello: rinomina la cartella mu-plugins via SSH/FTP.
• OPcache cache un'errore vecchio: Esegui opcache_reset() oppure riavvia php-fpm per pulire la cache.
• SFTP non funziona per timeout: Cambia porta o usa key auth: alcuni ISP bloccano porta 22.
• Plesk WP Toolkit non vede il sito: Sito installato manualmente: registralo in WP Toolkit con 'Scan'.

Domande frequenti

D: WP Error Monitor funziona anche con WSOD totale?
R: Sì, perchè l’agent registra l’handler in fase early e usa shutdown function: cattura anche fatal di parse error nei plugin.

D: Posso vedere lo stack trace completo?
R: Sì, se il fatal è una Throwable. I parse error PHP non hanno stack trace per natura.

D: Cosa faccio se neanche WP Error Monitor riceve l’evento?
R: Probabile errore in wp-config.php (prima del caricamento agent): controlla manualmente via SSH cat wp-content/debug.log.

D: Quanto è rapido un rollback Plesk snapshot?
R: Tipicamente 30-60 secondi per ripristinare uno snapshot pre-update.

D: Posso prevenire tutti i WSOD?
R: No, ma le best practice li riducono drasticamente. Importante la rapida diagnosi.

Hai bisogno di aiuto?

Se vuoi affidare il monitoraggio WordPress al team di G Tech Group, scrivici tramite il modulo di contatto.