Una schermata bianca della morte PrestaShop è una pagina vuota senza alcun messaggio – nel front office, nel Back Office o in entrambi. Di solito significa che PHP si è interrotto prima che il negozio potesse renderizzare l’HTML. Questa guida mostra come attivare la modalità debug (anche quando l’amministrazione è inattiva), leggere il vero errore e applicare le correzioni che risolvono la maggior parte dei casi di WSoD.
Da PrestaShop 1.7 in poi (inclusi 8 e 9), le opzioni di debug si trovano in Parametri avanzati → Prestazioni quando il Back Office si carica ancora. Se anche l’amministrazione è vuota, devi modificare _PS_MODE_DEV_ in config/defines.inc.php tramite SFTP o SSH. Le note ufficiali sulla schermata si trovano nella documentazione sulle Prestazioni di PrestaShop 9. Esegui un backup completo di PrestaShop prima di eliminare moduli o ripristinare file.
Cosa significa di solito una schermata bianca della morte PrestaShop
La pagina vuota è un sintomo, non un singolo bug. Una schermata bianca della morte PrestaShop significa che PHP ha riscontrato un errore fatale, ha esaurito la memoria o ha fallito prima che Smarty potesse stampare qualcosa. La modalità di produzione nasconde quel dettaglio di proposito – in modo che gli acquirenti non vedano mai uno stack trace. Il tuo compito è rendere visibile l’errore, quindi correggere la causa.
Nota dove fallisce:
- Solo front – spesso un override del tema, un hook di un modulo o un artefatto della cache sulla vetrina
- Solo Back Office – spesso un modulo di amministrazione, una scheda o un override in
override/ - Entrambi – credenziali del DB errate,
defines.inc.phpcorrotto, crash della versione PHP o un errore fatale che viene eseguito ad ogni richiesta
Passo 1: Abilita la modalità debug
La modalità debug stampa l’eccezione (o ti indirizza al log) invece di una pagina bianca. Preferisci il Back Office quando si apre ancora.
- Accedi al Back Office.
- Vai in Parametri avanzati → Prestazioni.
- Nel blocco Modalità debug, imposta Modalità debug su Sì.
- Clicca su Salva.
- Ricarica l’URL vuoto in una finestra privata.
Se anche il Back Office è una schermata bianca della morte PrestaShop, modifica il file sul disco. Scarica prima una copia di config/defines.inc.php (anche se hai già fatto un backup completo del negozio) in modo da poter rimettere l’originale con un clic se la modifica va storta:
- Apri
config/defines.inc.phptramite SFTP, SSH o il file manager dell’hosting e salva una copia locale. - Trova
define('_PS_MODE_DEV_', false);(la dicitura potrebbe variare leggermente in base alla versione). - Cambialo in
define('_PS_MODE_DEV_', true);e salva. - Ricarica la pagina che non funziona.
Disattiva di nuovo il debug quando hai finito. Lasciarlo attivo in produzione espone percorsi e stack trace a chiunque incontri un errore.
Passo 2: Identifica l’errore
Con il debug attivo, la schermata bianca della morte PrestaShop di solito diventa un’eccezione leggibile. Nota il nome della classe, il nome del modulo, il percorso del file sotto modules/, themes/ o override/ e il numero di riga. Quella stringa è di solito sufficiente per scegliere la correzione giusta qui sotto.
Se la pagina rimane vuota anche con _PS_MODE_DEV_ su true, controlla il log degli errori PHP dell’hosting (cPanel, Plesk o var/logs/ su alcune configurazioni). Un errore di sintassi in un file di configurazione può interrompere l’esecuzione prima che il livello di debug di PrestaShop entri in funzione.
Fonti comuni:
- Personalizzazioni recenti – modifiche al tema, override o snippet copiati
- Moduli – specialmente un modulo installato o aggiornato subito prima del crash
- Modifiche all’hosting – aggiornamento della versione PHP, estensione mancante, limite di memoria inferiore
- Credenziali del database – valori errati in
app/config/parameters.phpdopo una migrazione - Permessi dei file – PHP non può leggere un file richiesto o scrivere nella cache
- Limite di memoria – errori fatali che menzionano memoria esaurita
- Cache obsoleta – template compilati corrotti dopo un aggiornamento
Passo 3: Correggi l’errore
Abbina l’output di debug a un percorso. Cambia una cosa alla volta, quindi ricarica.
Personalizzazioni e override
Annulla l’ultima modifica al tema o all’override se la conosci. In Prestazioni, prova Disattiva tutti gli override → Sì, salva e riprova. Se il negozio torna a funzionare, il bug è in override/ o nell’override di un modulo – correggi o rimuovi quel file piuttosto che lasciare gli override disattivati per sempre.
Bug dei moduli
In Prestazioni, imposta Disattiva i moduli non di PrestaShop → Sì e riprova. Se questo risolve la schermata bianca della morte PrestaShop, rinomina la cartella del modulo sospetto sotto modules/ (o disinstallalo dal BO una volta che l’amministrazione funziona) uno alla volta finché non trovi il colpevole. Preferisci rinominare piuttosto che eliminare, in modo da poter ripristinare i file dopo averlo identificato.
Hosting e PHP
Confronta Parametri avanzati → Informazioni con ciò che l’hosting dichiara di eseguire. Dopo un aggiornamento di PHP, estensioni mancanti o una gestione degli errori più rigorosa spesso si manifestano come una pagina vuota. Chiedi all’hosting quale versione di PHP e quale memory_limit utilizza effettivamente il vhost.
Connessione al database
Se il debug menziona l’accesso al database o il negozio ha smesso di funzionare subito dopo un trasferimento di server, verifica host, nome, utente e password in app/config/parameters.php. I passaggi completi si trovano nella nostra guida su come modificare le impostazioni di connessione al database in PrestaShop.
Permessi e memoria
Quando l’errore nomina un file che PHP non può aprire, correggi la proprietà/i permessi per quel percorso (tipica proprietà dell’utente web; evita 777 come correzione permanente). Per gli errori di memoria esaurita, aumenta il memory_limit nel php.ini del vhost o chiedi all’hosting – quindi svuota la cache e riprova.
Cache
Da Prestazioni, clicca su Pulisci la cache. Se il BO è inattivo, elimina il contenuto di var/cache/prod/ (e var/cache/dev/ se presente) tramite file manager o SSH, mantenendo le cartelle stesse. Alberi di cache enormi sono spesso più facili da svuotare da SSH che da FTP.
Passo 4: Quando hai ancora bisogno di aiuto
Se il debug è attivo, i moduli/override sono isolati, le credenziali corrispondono e hai ancora una schermata bianca della morte PrestaShop, raccogli: il testo esatto dell’errore, la versione di PrestaShop, la versione di PHP e cosa è cambiato di recente (modulo, deploy, aggiornamento dell’hosting). Pubblica questi dati sui forum di PrestaShop, o inviali al tuo hosting o a uno sviluppatore che può leggere i log del server che non puoi vedere solo dal negozio.
Passo 5: Ripristina dal backup
Ripristinare i file o un dump del DB è l’ultima risorsa – perdi le modifiche fatte dopo quel backup. Usalo quando un deploy errato non può essere annullato rapidamente e hai già una copia recente. Come creare e conservare queste copie è spiegato nella guida al backup di PrestaShop.
Lista di controllo rapida
- Abilita il debug (Prestazioni nel BO, o
_PS_MODE_DEV_indefines.inc.php). - Leggi l’errore sullo schermo o il log PHP.
- Isola gli override e i moduli non nativi da Prestazioni.
- Correggi le credenziali del DB, i permessi, la memoria o la cache come indicato dal messaggio.
- Disattiva il debug; ripristina dal backup solo se nient’altro recupera il negozio.
La maggior parte dei casi di schermata bianca della morte PrestaShop si risolvono una volta che il vero messaggio PHP è visibile. Inizia con la modalità debug, cambia una variabile alla volta e tieni pronto un percorso di backup prima di eliminare qualsiasi cosa che non puoi rimettere al suo posto.