Attivare il debug log di WordPress (WordPress Debug Mode)

Quando apri il tuo sito WordPress e ottieni una pagina bianca o un errore 500, WordPress sta sopprimendo un messaggio di errore che identificherebbe immediatamente la causa. Attivare il WordPress debug log dice a WordPress di scrivere ogni errore, avviso e notice PHP in un file — wp-content/debug.log — così puoi vedere esattamente quale Plugin, Theme o riga di codice è responsabile.

TL;DR: aggiungi queste tre costanti a wp-config.php, direttamente sopra la riga /* That's all, stop editing! Happy publishing. */ — define( 'WP_DEBUG', true );, define( 'WP_DEBUG_LOG', true ); e define( 'WP_DEBUG_DISPLAY', false );. Dopo il salvataggio, ricarica la pagina e WordPress scrive tutti gli errori PHP in wp-content/debug.log. Quando hai finito la risoluzione dei problemi, disattiva la WordPress debug mode prima del push in produzione.

WordPress Debug Mode per ambiente Hosting

Come accedere a wp-config.php — e dove finisce debug.log — dipende dal tuo ambiente Hosting. Usa la sezione che corrisponde alla tua configurazione.

Hosting condiviso (cPanel / FTP)

Sugli host condivisi come Bluehost, SiteGround o Hostinger, wp-config.php si trova nella directory principale di WordPress, tipicamente public_html/. Modificalo usando il File Manager di cPanel o un client FTP come FileZilla.

Problema comune di permessi: se WordPress non può scrivere debug.log, la directory wp-content/ deve essere scrivibile dal web server. Il permesso standard è 755 per le directory. Non impostarlo su 777 su un host condiviso — rende la directory scrivibile a tutti ed è un rischio di sicurezza.

Dai ticket di supporto WP STAGING, l’Hosting condiviso è dove debug.log più spesso fallisce silenziosamente, perché molti host condivisi catturano gli errori PHP nel proprio log lato server piuttosto che permettere a WordPress di creare debug.log. Se il file non appare mai dopo aver attivato WP_DEBUG, chiedi al tuo host dove è memorizzato il loro log degli errori PHP.

VPS / Server gestito (SSH)

Con accesso SSH, modifica wp-config.php direttamente da riga di comando:

nano /var/www/html/wp-config.php

Dopo il salvataggio, segui il log in tempo reale per osservare gli errori non appena si verificano:

tail -f /var/www/html/wp-content/debug.log

Se debug.log non viene creato, verifica che la directory wp-content/ sia di proprietà dell’utente del web server (www-data su Ubuntu/Debian, apache o nginx su CentOS/AlmaLinux):

ls -la /var/www/html/wp-content/
chown www-data:www-data /var/www/html/wp-content/

Sviluppo locale (LocalWP / DevKinsta / XAMPP)

debug.log appare nella stessa posizione wp-content/debug.log, ma il percorso base dipende dal tuo ambiente locale:

• LocalWP: ~/Local Sites/<site-name>/app/public/wp-content/debug.log
• DevKinsta: ~/DevKinsta/projects/<site-name>/app/public/wp-content/debug.log
• XAMPP su Windows: C:xampphtdocs<site-name>wp-contentdebug.log

Gli ambienti locali raramente hanno problemi di permessi perché il web server e il tuo account utente vengono eseguiti come lo stesso processo. Se debug.log non appare mai, conferma che il tuo wp-config.php sia nella radice di WordPress e non in una directory genitore.

Sito di staging WP STAGING

Nei nostri test con WP STAGING, attivare la debug mode sul clone di staging è l’approccio più sicuro — il clone è una copia esatta del sito live, quindi tutti gli errori che riproduci corrisponderanno all’ambiente live senza interessare i visitatori reali.

Per attivare la debug mode sul tuo sito di staging, modifica wp-config.php all’interno della directory di staging. WP STAGING crea il sito di staging come sottodirectory o sottodominio separato con il proprio wp-config.php, quindi le modifiche lì non influiscono sull’impostazione WP_DEBUG del sito live.

Se non riesci ad accedere al tuo sito di staging, il debug log è il primo posto da controllare — i fallimenti di login su staging sono molto spesso errori fatali PHP che appaiono solo nel log.

Come attivare la WordPress Debug Mode

Puoi attivare la "debug mode" di WordPress modificando alcune righe nel file wp-config.php della tua installazione WordPress:

1. Accedi a cPanel o accedi al tuo sito via FTP
2. Usa il File Manager di cPanel o il tuo client FTP e modifica il file wp-config.php
3. Copia le righe qui sotto nel file wp-config.php oppure, se già esistono, cambia i loro valori in true:

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

Attenzione: assicurati di copiare le righe esattamente come mostrate e non dimenticare un punto e virgola o altri caratteri!

1. Incolla le righe copiate direttamente sopra la riga che dice
   /* That's all, stop editing! Happy publishing. */

Dopo aver ricaricato il sito, WordPress scriverà tutti gli errori PHP nel file debug.log.
WordPress salva quel file nella cartella: wp-content/debug.log

Mostrare gli errori sul frontend WordPress

Se vuoi vedere gli errori del debug log direttamente sullo schermo invece di attivare il file debug.log, cambia la riga che dice define( 'WP_DEBUG_DISPLAY', false );

Rinominala in: define( 'WP_DEBUG_DISPLAY', true );.

WordPress non crea il file debug.log

Alcuni provider Hosting[1] non permettono la creazione del debug.log di WordPress. Catturano tutti gli errori PHP e li fanno scrivere a WordPress in un file di log separato.

Se WordPress non riesce a creare debug.log, segui questo albero decisionale per trovare la causa:

1. Cerca un file di log alternativo. Controlla nella radice del sito un file chiamato error_log, oppure cerca una cartella /logs/. Molti host condivisi incluso HostGator reindirizzano gli errori PHP al proprio log lato server invece di permettere a WordPress di scrivere debug.log. Se non trovi file di log, chiedi al tuo provider Hosting dove memorizzano i log degli errori PHP.

2. Controlla i permessi della directory. wp-content/ deve essere scrivibile dal web server. Su un server con accesso SSH, esegui:

ls -la /path/to/wp-content/

La directory dovrebbe essere di proprietà di www-data (Ubuntu/Debian) o apache (CentOS). Il permesso standard è 755. Se la directory è di proprietà di root e l’utente del web server non può scriverci, debug.log fallirà silenziosamente nella creazione.

3. Verifica se display_errors sta sovrascrivendo le tue impostazioni. Alcune configurazioni server php.ini o direttive .htaccess impostano php_flag display_errors Off, che può sopprimere l’output anche quando WP_DEBUG_DISPLAY è true. Controlla le impostazioni PHP del pannello di controllo del tuo Hosting o chiedi al tuo host.

4. Verifica se un must-use Plugin sta sopprimendo gli errori. I file in wp-content/mu-plugins/ vengono caricati prima di tutto il resto e possono sovrascrivere i gestori di errori di WordPress. Se il tuo host ha installato un must-use Plugin che intercetta gli errori, può impedire la scrittura di debug.log. Ispeziona eventuali file in wp-content/mu-plugins/ se quella directory esiste.

5. Controlla il livello di error_reporting. Se error_reporting è impostato in modo troppo restrittivo — ad esempio, solo a E_ERROR — PHP non registrerà avvisi e notice. WordPress imposta error_reporting(E_ALL) quando WP_DEBUG è true, ma un Plugin o una configurazione del server può cambiare questo dopo che WordPress carica. Vedi la documentazione PHP di error_reporting per l’elenco completo delle costanti e cosa copre ciascun livello.

6. Verifica che la directory del percorso log esista. Se hai già impostato WP_DEBUG_LOG su un percorso personalizzato, conferma che la directory a quel percorso esista e sia scrivibile dal web server.

In alternativa, puoi usare il metodo menzionato sopra e cambiare
define( 'WP_DEBUG_DISPLAY', false ); in
define( 'WP_DEBUG_DISPLAY', true );

Se funziona, vedrai gli errori rilevanti sul frontend. Questo ti aiuterà a risolvere l’errore fatale.

Puoi trovare istruzioni più dettagliate sull’attivazione della WordPress debug mode nella documentazione WordPress Debugging.

Al momento della stesura di questo articolo: [1] HostGator

Metodo alternativo per il debug degli errori fatali quando debug.log non viene generato

A volte, quando attivi la WP_DEBUG mode per risolvere un errore fatale, potresti scoprire che il tuo provider Hosting impedisce la creazione del file debug.log. Anche impostare WP_DEBUG_DISPLAY a true non sempre aiuta a mostrare l’errore sul frontend.

Se sei bloccato in questa situazione, ecco una soluzione alternativa che funziona quando nient’altro funziona.

Forzare la visualizzazione degli errori in wp-config.php

Questo snippet forza la visualizzazione dell’errore fatale:

register_shutdown_function(function () {
    $error = error_get_last();
    if ($error) {
        print_r($error);
    }
});

🚨 Ricorda di rimuovere lo snippet dopo il debug e usalo solo quando hai accesso FTP per un rollback sicuro.

Leggere il debug log di WordPress

Una volta che debug.log esiste, aprilo in un editor di testo qualsiasi. Ogni riga segue questo schema:

[DD-Mon-YYYY HH:MM:SS UTC] PHP Fatal error: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Warning: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: <message> in /path/to/file.php on line N

Ecco cosa significa ogni classe di errore e quando agire:

PHP Fatal error — PHP ha smesso di eseguire. Questa è sempre la causa di una pagina bianca o di un errore 500. Il percorso del file e il numero di riga nella voce del log mostrano esattamente dove guardare. Trova il Plugin o Theme il cui file è nominato nella voce e disattivalo per confermare.

PHP Warning — PHP ha incontrato qualcosa di inaspettato ma ha continuato a funzionare. Gli avvisi non causano pagine bianche da soli, ma spesso indicano un bug che diventerà un errore fatale in condizioni diverse. Se stai attivando il debug log di WordPress per identificare avvisi PHP relativi ai limiti di configurazione PHP, un avviso max_input_vars da un Plugin con molti form è una voce comune.

PHP Notice — PHP ha notato un potenziale problema come una variabile non definita. I notice raramente indicano un vero bug in produzione, ma se lo stesso notice appare migliaia di volte per caricamento di pagina, può segnalare un problema di loop o ricorsione che degrada le prestazioni.

Errori database $wpdb — Le righe che iniziano con WordPress database error indicano che una query è fallita. Queste di solito puntano a un Plugin che genera una query SQL malformata o a un problema nelle tabelle del database WordPress a cui la query mira. Il messaggio di errore include la query che è fallita, il che rende il Plugin responsabile facile da identificare.

Quando trovi un errore fatale o un avviso ripetuto, guarda il percorso del file nella voce del log. Se appartiene a un Plugin o Theme, disattivalo, ricarica la pagina e conferma che le voci del log si fermano.

Se il debug log mostra errori REST API in WordPress, la voce del log tipicamente nomina la funzione esatta che è fallita — segui la guida dedicata da quel punto di partenza. Se mostra errori ERR_CONNECTION_REFUSED, quelli hanno origine a livello server o di rete piuttosto che in PHP. Per gli errori 414 Request-URI Too Large, il log di solito identifica quale Plugin sta generando l’URL sovradimensionato.

Cambiare la posizione di debug.log

Puoi cambiare il percorso che WordPress usa per il logging degli errori cambiando il valore della costante WP_DEBUG_LOG.

Apri wp-config.php e trova la riga che contiene WP_DEBUG_LOG.

Cerca: define( 'WP_DEBUG_LOG', true );

Rinomina in: define( 'WP_DEBUG_LOG', '/logs/errors.log' );

Questo permette a WordPress di scrivere i messaggi di errore in un percorso file diverso.

Come percorso di destinazione puoi anche usare /dev/stderr o /dev/stdout. È utile in Docker o altri ambienti containerizzati dove vuoi tutti i log in un flusso di output condiviso.

Disattivare la debug mode in WordPress dopo la risoluzione dei problemi

Una volta che hai finito le indagini, disattiva immediatamente la debug mode. Il file debug.log è accessibile dal web per impostazione predefinita su wp-content/debug.log e può contenere dettagli sugli errori del database, percorsi file e altre informazioni sul server che non dovrebbero essere pubblicamente leggibili.

Elimina il file debug.log e disattiva ulteriori log degli errori cambiando define( 'WP_DEBUG', true ); di nuovo in define( 'WP_DEBUG', false );.

Disattiva sempre la WordPress debug mode prima del push in produzione quando lavori su un sito di staging. Il workflow di push di WP STAGING è il checkpoint giusto per confermare che WP_DEBUG sia off prima che il clone sovrascriva il sito live.

Articoli correlati

• Pagina bianca su un sito di staging WordPress
• Come risolvere un errore 500 e la pagina bianca di WordPress
• Come fare il debug degli errori JavaScript nella console del browser