DBALException su PrestaShop: l'errore TLS/SSL che blocca tutto

Il sito è completamente offline, senza aver toccato nulla

Lo scenario spiazza: non ha rilasciato nulla, non ha aggiornato nulla, e il negozio mostra una pagina di errore completa, front office e back office compresi. Nei log compare una DBALException PrestaShop di questo tipo:

An exception occurred while establishing a connection to figure out your platform version
SQLSTATE[HY000] [2026] TLS/SSL error: invalid directory

Questo messaggio non ha nulla a che vedere con un bug del suo negozio. Compare quando il suo hosting provider migra il server di database a MariaDB 11.4 o a una versione più recente.

Che cosa succede davvero

Si combinano due meccanismi.

Primo meccanismo: Doctrine interroga la versione del server. PrestaShop 1.7 e 8 usano Doctrine DBAL. All'apertura della connessione Doctrine esegue una query per determinare la versione del motore e adattare di conseguenza la propria grammatica SQL. È questa query preliminare a fallire, da cui la formula «to figure out your platform version».

Secondo meccanismo: MariaDB 11.4 irrigidisce la verifica TLS. A partire da questa versione il client MariaDB verifica per impostazione predefinita il certificato del server. Su un hosting condiviso che usa CloudLinux e CageFS ogni account è isolato in un file system virtuale, e la libreria client non vi trova l'archivio dei certificati radice di sistema. Restituisce quindi invalid directory: non trova la directory dei certificati.

Il codice 2026 nel messaggio non è un anno: è il codice di errore client di MariaDB per un handshake fallito.

Soluzione 1: passare ai driver nativi

È la correzione più rapida e non tocca il codice.

Nel pannello del suo hosting apra il selettore della versione di PHP e delle estensioni associate. Sostituisca:

• pdo_mysql con nd_pdo_mysql
• mysqli con nd_mysqli

Le varianti «nd» (native driver) usano l'implementazione nativa di PHP invece della libreria client MariaDB, e non dipendono quindi dall'archivio certificati di sistema.

Poi svuoti var/cache/prod/ e ricarichi la pagina. Nella stragrande maggioranza dei casi il negozio torna online all'istante.

Su un hosting privo di selettore PHP, chieda l'intervento all'assistenza citando il messaggio di errore esatto: è un caso noto.

Soluzione 2: forzare la configurazione di Doctrine

Se non ha accesso alle estensioni PHP, intervenga lato applicativo in app/config/doctrine.yml.

Dichiarare la versione del server evita la query di rilevamento che fallisce:

doctrine:
    dbal:
        server_version: '11.4'

Disattivare la verifica del certificato se la connessione continua a essere rifiutata:

doctrine:
    dbal:
        options:
            1007: false

La chiave 1007 corrisponde alla costante MYSQLI_OPT_SSL_VERIFY_SERVER_CERT. Da usare soltanto quando il database si trova sullo stesso server o su una rete privata: sta disattivando un controllo di sicurezza reale.

Dopo ogni modifica elimini il contenuto di var/cache/: Symfony tiene in cache la configurazione compilata e la sua modifica resterebbe senza effetto.

Verificare che la diagnosi sia quella giusta

Prima di applicare qualsiasi cosa, confermi l'ipotesi:

mysql --version

Una versione 11.4 o superiore lato server conferma lo scenario.

php -m | grep -i mysql

Questo comando elenca le estensioni attive e permette di capire quale sia caricata.

Infine provi una connessione diretta con le credenziali di app/config/parameters.php. Se la connessione da riga di comando funziona mentre PrestaShop fallisce, il problema sta nel livello client di PHP e non nelle credenziali.

Gli errori da non commettere

Non reinstalli PrestaShop. L'errore è ambientale: una reinstallazione non cambia nulla e le fa perdere la configurazione.

Non cambi le credenziali di connessione. Sono valide. Il messaggio parla di TLS, non di autenticazione rifiutata.

Non ripristini un vecchio backup. Il suo codice non è cambiato. Un ripristino le farebbe perdere gli ordini ricevuti nel frattempo, senza correggere nulla.

Non elimini var/cache in quanto tale, soltanto il suo contenuto: rischia di generare un secondo errore che confonde la diagnosi.

Prepararsi al prossimo episodio

Questo tipo di guasto, provocato da un'evoluzione infrastrutturale lato hosting, si moltiplica man mano che i parchi server vengono migrati. Due abitudini ne limitano l'impatto:

• Leggere le comunicazioni di manutenzione del proprio hosting. Le migrazioni del motore di database vengono annunciate, spesso con diverse settimane di anticipo, in un'e-mail che nessuno legge.
• Avere un ambiente di staging sullo stesso hosting. Di solito viene migrato prima o in contemporanea, e la avverte prima che cada la produzione.

Per gli altri guasti che mettono completamente offline un negozio, la nostra checklist errore 500 illustra il metodo di diagnosi generale.

Negozio offline in questo momento?

Diagnostichiamo questo tipo di guasto ambientale in meno di un'ora e, se serve, trattiamo direttamente con il suo hosting provider. Veda l'assistenza PrestaShop.