Come individuare quale plugin o tema ha causato un errore critico dopo un aggiornamento

Introduzione: cosa sapere subito

Se dopo un aggiornamento il sito mostra “Si è verificato un errore critico” è importante procedere con cautela: evitare rollback senza un backup e, se possibile, intervenire in orari di basso traffico per limitare l’impatto sugli utenti. Gli strumenti di debug (come WP_DEBUG e WP_DEBUG_DISPLAY) sono pensati principalmente per staging o ambienti di sviluppo; non abilitarli in produzione senza comprenderne i rischi.

Questa guida offre una procedura pratica e non distruttiva per raccogliere informazioni, isolare il componente responsabile (plugin o tema) e ripristinare l’accesso al sito usando metodi sicuri (es. rinominare cartelle, impostare active_plugins su a:0:{}). Le indicazioni si basano sulle linee guida ufficiali di WordPress.

Perché succede: cause comuni di un errore critico post-aggiornamento

Le cause più frequenti sono conflitti o incompatibilità introdotte da un plugin o dal tema, una versione PHP non supportata, il superamento dei limiti di memoria PHP o file WordPress corrotti. Messaggi come “Allowed memory size exhausted” o “Maximum execution time exceeded” indicano problemi di risorse server e richiedono interventi sulla configurazione o il coinvolgimento del provider di hosting.

Interpretare il tipo di errore aiuta a scegliere la strategia corretta: i conflitti plugin/tema richiedono isolamento dei componenti, mentre i problemi di risorse richiedono aggiustamenti di configurazione o supporto hosting.

Prima di agire: backup e precauzioni

Prima di qualsiasi intervento è fortemente raccomandato avere un backup completo di file e database. Senza un backup creato prima dell’aggiornamento un rollback efficace è spesso impossibile e può provocare perdita di dati. Documentare lo stato del sito (log, versione plugin/tema) facilita il ripristino o la riproduzione del problema in staging.

Evitare di abilitare WP_DEBUG_DISPLAY su siti in produzione senza mitigazioni: la documentazione sconsiglia l’uso diretto degli strumenti di debug in produzione perché possono mostrare messaggi sensibili e alterare l’esperienza utente.

Raccogliere informazioni: usare log e debug in modo sicuro

Per ottenere dettagli tecnici utili, consultare i log disponibili: wp-content/debug.log (se WP_DEBUG e WP_DEBUG_LOG sono abilitati) e i log PHP/server forniti dall’hosting. Questi file contengono il tipo di errore, il file e la riga interessati.

Per attivare il minimo indispensabile di logging in wp-config.php usare:

// Attenzione: abilitare in staging o con cautela in produzione
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
// Evitare WP_DEBUG_DISPLAY=true in produzione senza precauzioni

Ricorda che WP_DEBUG_LOG scrive su wp-content/debug.log solo se WP_DEBUG è true. Oltre a debug.log, richiedi al provider i log PHP/server (error_log) per avere il contesto completo.

Recovery Mode e .maintenance: cosa aspettarsi

WordPress dispone di un gestore per errori fatali che può attivare la Recovery Mode per consentire l’accesso all’area admin con messaggi e link per intervenire su plugin o temi. Quando pertinente, WordPress invia un’email all’amministratore con dettagli dell’errore e, se applicabile, un link per entrare in Recovery Mode.

Non confondere Recovery Mode con il file .maintenance: durante un aggiornamento automatico WordPress crea .maintenance nella root; se il sito resta bloccato sul messaggio “Briefly unavailable for scheduled maintenance” la soluzione è rimuovere manualmente il file .maintenance via FTP. Recovery Mode è il meccanismo di gestione degli errori; .maintenance è un file da eliminare se l’aggiornamento non è stato completato.

Isolare il colpevole: procedura passo‑passo

Di seguito tre metodi pratici, ordinati per scenario.

Metodo A — hai accesso all’area amministrativa

1. Disattiva tutti i plugin dalla schermata Plugin.
2. Verifica il sito; se il problema scompare, riattiva i plugin uno per uno fino a riprodurre l’errore e identificare il colpevole.

Metodo B — non hai accesso all’admin: via FTP/File Manager

1. Collegati via FTP o file manager e rinomina la cartella wp-content/plugins in plugins.off (o simile) per disattivare tutti i plugin preservandone le impostazioni.
2. Controlla il sito. Se torna disponibile, rinomina la cartella di nuovo in plugins e poi rinomina singole cartelle dei plugin per riattivarli a gruppi o uno per uno fino a individuare l’origine.

Metodo C — non hai accesso all’admin: via phpMyAdmin

1. Accedi a phpMyAdmin e nella tabella wp_options trova l’opzione active_plugins.
2. Imposta il valore serializzato su a:0:{} per disattivare tutti i plugin via DB.

Test del tema

Se il problema potrebbe essere causato dal tema, attiva un tema WordPress di default (es. Twenty Twenty-One) dall’admin oppure, via FTP, rinomina la cartella del tema attivo per forzare il fallback al tema predefinito. Tenere presente che rinominare cartelle impatta tutti gli utenti e va eseguito preferibilmente in orario di bassa attività.

Dopo aver isolato il componente, documenta la versione del plugin/tema e i log associati prima di ripetere aggiornamenti o aggiornare nuovamente il componente.

Problemi di risorse server: come interpretare e mitigare

Se dai log emergono messaggi come “Allowed memory size exhausted” o “Maximum execution time exceeded”, le azioni possibili includono aumentare memory_limit in wp-config.php o php.ini, impostare php_value max_execution_time in .htaccess, oppure chiedere al provider di aumentare i limiti del server. Le modalità di modifica dipendono dall’ambiente di hosting: se non sei sicuro, coinvolgi il supporto del provider.

Dopo il recupero: verifiche e riattivazione controllata

Dopo aver ripristinato l’accesso o disattivato il componente responsabile, è fondamentale: documentare la causa (log, versione plugin/tema), conservare i file di log e usare la procedura di riattivazione uno‑per‑uno per evitare di riintrodurre l’errore. Segui la raccomandazione di disattivare i plugin prima di grandi aggiornamenti e di testare le modifiche in staging.

Quando ripristinare da backup

Se il sito è gravemente compromesso o non esiste un percorso di diagnosi rapido, preferisci un ripristino da backup completo precedente all’aggiornamento; tuttavia, un ripristino può sovrascrivere dati recenti, quindi documenta lo stato attuale e conserva i log prima del ripristino.

Checklist rapida di emergenza

1. Verifica la presenza di un backup completo (file + DB) creato prima dell’aggiornamento.
2. Se il sito mostra la pagina di maintenance persistentemente, rimuovi .maintenance via FTP.
3. Se non si accede al pannello, disattiva i plugin rinominando wp-content/plugins o impostando active_plugins a:0:{} nel DB.
4. Se possibile, abilita WP_DEBUG e WP_DEBUG_LOG in ambiente di staging o con cautela per generare wp-content/debug.log.
5. Riattiva i plugin uno per uno e documenta il colpevole prima di aggiornare nuovamente.

Risorse ufficiali

Consulta le pagine ufficiali WordPress sul debugging, sull’handling degli errori e sugli aggiornamenti per dettagli tecnici e link diretti alle procedure citate qui.