Risoluzione problemi PrestaShop: schermate bianche ed errori 500

L’Approccio al Troubleshooting

Qualcosa si è rotto. L’istinto è quello di iniziare a cambiare cose a caso. Resistete. Modificare più cose contemporaneamente rende impossibile capire quale intervento abbia risolto il problema. Il metodo che funziona: osservate, isolate, correggete, verificate. Leggete l’errore. Controllate i log. Cambiate una sola cosa. Testate. Ripetete.

Prima di toccare qualsiasi cosa, fate un backup. Dump del database + archivio dei file. Se la correzione peggiora le cose, avete bisogno di un modo per tornare indietro.

1. Attivare la Modalità Debug

La modalità debug è il primo strumento per ogni problema. PrestaShop nasconde gli errori di default — ottimo per i clienti, pessimo per il troubleshooting.

PrestaShop 1.6 e 1.7

Modificate config/defines.inc.php:

define('_PS_MODE_DEV_', true);  // Change false to true

Questo attiva la visualizzazione degli errori, disabilita la cache di Smarty e imposta error_reporting su E_ALL. Su PS 1.7.7+, abilita anche la toolbar di debug Symfony in fondo a ogni pagina.

PrestaShop 8.x e 9.x

Lo stesso approccio con defines.inc.php funziona, ma PS 8+ legge anche da .env:

# .env or .env.local
APP_ENV=dev
APP_DEBUG=1

Fallback di Emergenza

Se l’errore si verifica prima che PrestaShop carichi la sua configurazione, forzate la visualizzazione degli errori PHP all’inizio di index.php:

ini_set('display_errors', 1);
error_reporting(E_ALL);

Su PS 1.7.7+, la modalità debug abilita anche la toolbar del profiler Symfony che mostra ogni query al database, l’utilizzo della memoria, gli hit/miss della cache è i template renderizzati.

Non lasciate mai la modalità debug attiva in produzione. Espone percorsi di file, dettagli del database e logica interna a chiunque.

2. White Screen of Death (WSOD)

Una pagina bianca vuota significa che PHP ha riscontrato un errore fatale ma display_errors è disattivato. L’errore esiste — è solo nascosto.

Passo 1: Controllate il Log degli Errori

L’errore è sempre registrato da qualche parte: var/logs/prod.log (PS 1.7), var/log/prod.log (PS 8+/9), log degli errori Apache o log degli errori PHP. Su hosting condiviso: ~/logs/error.log.

Passo 2: Attivate la Modalità Debug

Se i log non sono accessibili, attivate _PS_MODE_DEV_ e ricaricate la pagina.

Passo 3: Verifica PHP da CLI

Se la pagina è completamente vuota, testate con PHP: php -l config/defines.inc.php (controllo sintassi) oppure php -r "require 'config/config.inc.php';" (test di caricamento).

Cause Più Comuni

• Limite di memoria esaurito: Aumentatelo in php.ini: memory_limit = 512M (minimo 256M per PS 1.7+, 512M per PS 8+).
• Versione PHP incompatibile: PS 1.6 non funziona con PHP 7.4+. PS 1.7.0-1.7.6 non funziona con PHP 8.0+. PS 9.x richiede PHP 8.1+.
• Errore fatale in un modulo: Rinominate la cartella del modulo via FTP: modules/problem_module in modules/problem_module_disabled.
• Cache corrotta: Cancellate tutto il contenuto di var/cache/ (PS 1.7+) o cache/smarty/compile/ (PS 1.6).
• Override corrotto: Rinominate temporaneamente la directory override/ per verificare.

3. Errore 500 Internal Server Error

HTTP 500 significa che il server ha incontrato una condizione che non è riuscito a gestire. A differenza del WSOD, potrebbe non raggiungere nemmeno PHP.

Problemi con .htaccess

La causa più comune. Testate rinominando temporaneamente: mv .htaccess .htaccess.bak. Se il sito si carica (con URL non funzionanti), il problema è il .htaccess.

• mod_rewrite non abilitato: a2enmod rewrite && systemctl restart apache2
• AllowOverride None: Deve essere AllowOverride All nella configurazione del virtual host.
• Direttive non supportate: Alcuni hosting condivisi bloccano Options o php_value. Commentate le sezioni una alla volta fino a trovare quella problematica.
• Rigenerazione: Shop Parameters → Traffic & SEO → "Generate .htaccess file".

Permessi dei File

Directory: 755, file: 644, directory scrivibili (var/cache, img, upload): 775. Mai 777.

find /path/to/prestashop -type d -exec chmod 755 {} \\;
find /path/to/prestashop -type f -exec chmod 644 {} \\;

Limiti PHP

memory_limit = 512M
max_execution_time = 300
max_input_vars = 10000
post_max_size = 64M
upload_max_filesize = 64M

max_input_vars viene spesso trascurato — le pagine prodotto di PS con combinazioni superano il valore predefinito di 1000.

4. Conflitti tra Moduli

I moduli sono la fonte più comune di problemi. Due moduli che cercano di fare la stessa cosa entreranno in conflitto.

Il Metodo di Isolamento

1. Disattivate tutti i moduli di terze parti tramite il Module Manager.
2. Verificate che il problema sia scomparso.
3. Riattivate i moduli uno alla volta, testando dopo ciascuno.

Se il pannello admin è inaccessibile, disattivate via database:

UPDATE ps_module SET active = 0 WHERE name = 'module_name';
-- Or rename the folder: mv modules/problem_module modules/problem_module.bak

Conflitti di Override

Due moduli non possono sovrascrivere la stessa classe. Controllate override/classes/ e override/controllers/. Se rimuovete un override manualmente, cancellate var/cache/*/class_index.php per forzare la rigenerazione.

Priorità degli Hook

Quando due moduli utilizzano lo stesso hook, l’ordine di esecuzione è determinante. Regolatelo in Design → Positions, oppure interrogate ps_hook_module per vedere l’ordine di esecuzione per ogni hook.

Quando segnalate un conflitto tra moduli a uno sviluppatore, includete: l’errore esatto dal log, la versione di PS, la versione PHP, gli altri moduli attivi e i passaggi per riprodurre il problema.

5. Problemi di Cache

PrestaShop ha molteplici cache indipendenti. Quando "svuotare la cache" non funziona, probabilmente avete svuotato quella sbagliata.

I Livelli di Cache

• Smarty: File TPL compilati in var/cache/prod/smarty/.
• Symfony: Container, route e traduzioni compilate in var/cache/prod/.
• OPcache: Bytecode PHP nella memoria condivisa — invisibile al filesystem.
• Object cache: Cache delle query al database (basata su file o Redis).
• Cache del browser: CSS, JS, immagini sul dispositivo del visitatore.

Svuotare Tutto

Dal pannello admin: Advanced Parameters → Performance → Clear cache. Quando il pannello admin non funziona:

# Delete cache directories
rm -rf var/cache/prod/* var/cache/dev/*

# Or use Symfony console (PS 8+/9)
php bin/console cache:clear --env=prod

OPcache

Dopo aver modificato file PHP, OPcache potrebbe ancora servire la versione precedente. Resettate tramite una richiesta web — create un file temporaneo con opcache_reset();, visitatelo nel browser, cancellatelo. Il reset da CLI svuota solo la cache CLI, non quella web.

Quando la Cache Resta "Bloccata"

Associate la cache alla modifica: template → Smarty, codice PHP → OPcache, configurazione → Symfony, CSS/JS → browser (Ctrl+Shift+R). Controllate anche i permessi di var/cache/, cancellate class_index.php per forzare la rigenerazione e svuotate la CDN separatamente.

Dopo ogni deployment: svuotate la cache Symfony, la cache Smarty, OPcache (via web) e la cache CDN. Saltarne anche solo una farà sembrare che il deployment "non abbia funzionato."

6. Problemi con il Database

I problemi al database emergono solitamente dopo aggiornamenti falliti, importazioni interrotte o operazioni andate in timeout.

Tabelle Corrotte

# Check all tables
mysqlcheck -u root -p prestashop_db --check

# Repair (MyISAM only)
REPAIR TABLE ps_product;

# For InnoDB (most modern installs), rebuild in place:
ALTER TABLE ps_product ENGINE=InnoDB;

Colonne Mancanti Dopo un Aggiornamento Fallito

Errore: Unknown column 'new_column' in 'field list'. L’aggiornamento è stato interrotto, lasciando le tabelle incomplete.

# Check what columns exist
SHOW CREATE TABLE ps_product\\G

# Look for upgrade SQL in install-dev/upgrade/sql/ or install/upgrade/sql/
# Add the missing column manually:
ALTER TABLE ps_product ADD COLUMN `state` TINYINT(1) NOT NULL DEFAULT '1';

Confronto delle Strutture

Installate una copia pulita della vostra versione di PS, esportate entrambe le strutture con mysqldump --no-data e confrontatele con un diff per individuare tabelle, colonne e indici mancanti.

Query Bloccate

Eseguite SHOW FULL PROCESSLIST per trovare le query bloccate, KILL <id> per terminarle e SHOW ENGINE INNODB STATUS per controllare le attese sui lock.

Non eseguite mai ALTER TABLE su tabelle di produzione di grandi dimensioni durante l’orario lavorativo. Aggiungere una colonna a una tabella con un milione di righe può bloccarla per minuti.

7. Problemi con il Tema

Template Mancanti

Errore: unable to load template file 'module:modulename/...'. PrestaShop cerca prima nell’override del tema (themes/your_theme/modules/...), poi nel default del modulo. Se un override del tema fa riferimento a un file cancellato o rinominato, otterrete questo errore. Su Linux, i nomi dei file sono case-sensitive.

Errori di Compilazione Smarty

Tag non corrispondenti (ogni {if} richiede un {/if}), parentesi graffe JavaScript (racchiudete il JS in {literal}{/literal}) e problemi di encoding (i file TPL devono essere UTF-8 senza BOM) sono le cause più frequenti.

Errori nel Caricamento degli Asset

Controllate la console del browser (F12 → Network) per errori 404. Cause comuni: percorsi errati in theme.yml, cache CCC corrotta, configurazione CDN errata.

Problemi con i Temi Figlio

Tema padre eliminato (il figlio fallisce con "Invalid theme"), override di template non aggiornati dopo update del tema padre, o theme.yml incompleto nel tema figlio che causa la scomparsa dei moduli dagli hook.

Quando aggiornate PrestaShop, controllate il changelog per le modifiche ai template. Gli override del tema figlio per i template modificati devono essere aggiornati.

8. Compatibilità con le Versioni PHP

Matrice di Compatibilità

* PS 1.7.8 ha un supporto parziale per PHP 8.0 — il core funziona, ma molti moduli no.

Errori Comuni Durante l’Aggiornamento

• PHP 7.x → 8.0: TypeError: expects string, null given — PHP 8 è rigoroso con i valori null in strlen(), strpos(), ecc.
• PHP 8.0 → 8.1: Return type should be compatible — tipi più rigorosi. FILTER_SANITIZE_STRING deprecato.
• PHP 8.1 → 8.2: Proprietà dinamiche deprecate.

Importante: le versioni PHP da CLI e da web possono differire sui server multi-PHP. Verificate sempre con phpinfo() nel browser, non solo con php -v. Prima dell’aggiornamento: testate su uno staging, eseguite php -l sui file dei moduli, aggiornate prima i moduli.

9. Le Email Non Vengono Inviate

• Test dal pannello admin: Advanced Parameters → Email → "Send a test email."
• Controllate le impostazioni SMTP: Host, porta (587/TLS o 465/SSL), username, password.
• Controllate la tabella ps_mail: Se le email compaiono qui, PS le ha inviate — il problema è la consegna.
• PHP mail(): Se non funziona, passate a SMTP — più affidabile ovunque.
• Record DNS: SPF, DKIM, DMARC sono necessari per la consegna moderna.

Guida completa: PrestaShop Email Deliverability.

10. Improvviso Calo delle Prestazioni

Diagnostica Rapida

Controllate lo spazio su disco (df -h), il carico del server (uptime), MySQL (SHOW FULL PROCESSLIST) e lo stato di OPcache. Un disco pieno blocca silenziosamente tutto.

Rallentamenti Improvvisi Comuni

• Modalità debug rimasta attiva: Controllate _PS_MODE_DEV_ per prima cosa. Questo risolve più segnalazioni di "negozio lento" di qualsiasi altra soluzione.
• Disco pieno: MySQL va in crash, le cache non possono scrivere, i log non possono ruotare.
• Query problematica di un modulo: Una singola query senza indice su una tabella di grandi dimensioni può aggiungere secondi a ogni caricamento di pagina.
• Cron job sovrapposti: Molteplici script di importazione/indicizzazione in esecuzione simultanea.
• Tabelle sovradimensionate: ps_connections, ps_log, ps_cart crescono all’infinito senza manutenzione.

Guida completa: PrestaShop Performance Optimization.

11. Messaggi di Errore Comuni Spiegati

"Class 'SomeClass' not found"

Cancellate var/cache/prod/class_index.php (si rigenera automaticamente), eseguite composer dump-autoload (PS 1.7+) e verificate i nomi dei file case-sensitive su Linux. Se un modulo è stato parzialmente eliminato, ripulite le tabelle ps_hook_module e ps_module.

"CSRF token error" / "Invalid token"

Sessione scaduta (aumentate session.gc_maxlifetime), più schede admin aperte (aggiornate la pagina), reverse proxy che rimuove i cookie (escludete l’admin dal caching) o orologio del server non sincronizzato.

"Ajax error"

Aprite i DevTools (F12) → scheda Network. Riproducete l’errore. Trovate la richiesta fallita (in rosso, stato 500). La scheda Response mostra l’errore PHP effettivo.

"Allowed memory size exhausted"

Impostate memory_limit = 512M in php.ini o .htaccess. Se il negozio continua a richiedere più memoria, si tratta di un memory leak in un modulo — usate il profiler Symfony per trovare il colpevole.

"Duplicate entry for key"

Una violazione di vincolo di unicità. Comune con le importazioni di prodotti (riferimenti duplicati), installazioni di moduli su multistore o riesecuzione di aggiornamenti falliti.

"Deprecated: ..." a Raffica

Un avviso, non un errore. Per silenziarlo: error_reporting = E_ALL & ~E_DEPRECATED. Soluzione migliore: aggiornate il modulo. Questi avvisi diventeranno errori fatali nella prossima versione di PHP.

12. Ripristino di Emergenza

Reset della Password Admin

Per PS 1.6/1.7 (hashing MD5):

UPDATE ps_employee SET passwd = MD5(CONCAT(
    (SELECT value FROM ps_configuration WHERE name = '_COOKIE_KEY_'),
    'YourNewPassword!'
)) WHERE email = 'admin@yourdomain.com';

Per PS 8+/9 (bcrypt), caricate uno script PHP temporaneo che includa config/config.inc.php, utilizzi PrestaShop\\Core\\Crypto\\Hashing per generare l’hash, aggiorni ps_employee, poi cancellate lo script immediatamente.

Cancellate lo script di reset immediatamente dopo l’uso. Chiunque lo trovi potrebbe resettare qualsiasi password admin.

Disattivare un Modulo Rotto

-- Via database
UPDATE ps_module SET active = 0 WHERE name = 'broken_module';

-- Via filesystem (more reliable)
mv modules/broken_module modules/broken_module.disabled

Per disattivare tutti i moduli di terze parti in una volta, aggiornate ps_module impostando active = 0 per tutte le voci il cui nome NON rientra nell’elenco dei moduli nativi di PS (ps_banner, ps_categorytree, ps_facetedsearch, ecc.).

Disattivare gli Override

// config/defines.inc.php
define('_PS_ALLOW_OVERRIDES_', false);

Ripristino da Backup

Mettete il sito offline, ripristinate il database (mysql -u root -p db < backup.sql), ripristinate i file, svuotate tutte le cache (rm -rf var/cache/*), resettate OPcache, poi verificate che homepage, pagina prodotto, carrello, checkout e pannello admin funzionino correttamente.

Modalità Manutenzione Senza Accesso Admin

UPDATE ps_configuration SET value = '0' WHERE name = 'PS_SHOP_ENABLE';
UPDATE ps_configuration SET value = 'your.ip' WHERE name = 'PS_MAINTENANCE_IP';

13. Checklist Diagnostica

Stampate questa lista e procedete dall’alto verso il basso quando qualcosa va storto.

Fase 1: Raccogliere Informazioni

• Cosa è cambiato? Installazione/aggiornamento modulo, aggiornamento PS, aggiornamento PHP, modifica server, modifica tema?
• Quando esattamente è iniziato? Incrociate con i log di deployment e i cron job.
• Chi è interessato? Tutti gli utenti, browser specifici, solo l’admin, solo il front office?
• Qual è l’errore esatto? Attivate la modalità debug. Controllate la console del browser. Controllate tutti i log.

Fase 2: Isolare

• Server: spazio su disco (df -h), memoria (free -m), CPU (top), MySQL (SHOW PROCESSLIST)
• PHP: versione (php -v), controllo sintassi (php -l), impostazioni (phpinfo())
• Cache: svuotate tutti i livelli — Smarty, Symfony, OPcache, browser. Testate in navigazione privata.
• Moduli: disattivate quelli modificati di recente. Se non è chiaro, disattivate tutti quelli di terze parti e riattivate uno alla volta.
• Tema: passate temporaneamente a quello predefinito.
• Database: mysqlcheck, log degli errori MySQL, confrontate le strutture delle tabelle se dopo un aggiornamento.
• Permessi: ls -la su var/cache, var/logs, img, upload.

Fase 3: Correggere e Verificare

• Apportate UNA sola modifica alla volta. Testate. Se non ha risolto, annullate e provate la successiva.
• Svuotate tutte le cache dopo ogni correzione.
• Testate approfonditamente: homepage, categoria, prodotto, carrello, checkout, admin.
• Testate in navigazione privata / browser diverso.
• Disattivate la modalità debug. Rimuovete gli script temporanei.

Fase 4: Prevenire il Ripetersi

• Documentate cosa è successo e cosa lo ha risolto.
• Configurate il monitoraggio: uptime, log degli errori, spazio su disco.
• Verificate che i backup funzionino. Testate un ripristino.

Riferimento Rapido

Posizioni dei Log

• PS 1.6: log/ — PS 1.7: var/logs/ — PS 8+/9: var/log/
• Apache: /var/log/apache2/error.log — Nginx: /var/log/nginx/error.log
• MySQL: /var/log/mysql/error.log — PHP: secondo error_log in php.ini

File Chiave

• config/defines.inc.php — modalità debug, toggle degli override
• app/config/parameters.php — credenziali DB, secret (PS 1.7+)
• .env / .env.local — ambiente e debug (PS 8+)
• .htaccess — URL rewriting, impostazioni PHP, sicurezza

Comandi CLI Essenziali (PS 1.7+)

php bin/console cache:clear --env=prod
php bin/console prestashop:module list
php bin/console prestashop:module enable module_name
php bin/console prestashop:module disable module_name
composer dump-autoload -o

Ogni sessione di troubleshooting inizia allo stesso modo: controllate l’errore, controllate i log, isolate la causa. Gli sviluppatori più esperti non memorizzano ogni errore — sanno dove cercare. Questa guida vi fornisce quelle posizioni.