Mise à jour PrestaShop ratée : diagnostiquer et réparer rapidement

Table des matières :

1. Containment avant toute réparation : figer, sauvegarder, réduire la surface
2. Lire les logs là où ça casse : PHP, PrestaShop/Symfony, module d’upgrade
3. Pannes “infra” pendant un upgrade : PHP incompatible, limites, droits, cache opcode
4. Conflits applicatifs : modules, overrides, thème, autoload Composer
5. Base MySQL en état hybride : migrations incomplètes, collations, incohérences
6. Réparer vite : rollback, reprise de l’upgrade, ou bascule blue/green
7. Stabiliser le prochain upgrade : observabilité, CI, prérequis, hygiène de modules

Une mise à jour PrestaShop ratée n’est pas un “bug” unique : c’est un état incohérent entre (1) le code déployé, (2) le schéma/les données MySQL, (3) l’exécution PHP (version, extensions, limites), et (4) les caches (Smarty, Symfony, OPcache, Redis). Tant que vous ne qualifiez pas quel sous-système est en dérive, vous allez bricoler au hasard, et aggraver la période d’indisponibilité.

Sur PrestaShop 1.7/8/9, l’upgrade touche typiquement :

• des fichiers “core” (classes, controllers, Symfony, vendor/ selon votre mode de déploiement),
• des scripts d’upgrade PHP qui appliquent des migrations (ajout de colonnes, index, nouvelles tables, mises à jour de configuration),
• des modules natifs/tiers, dont certains injectent des overrides ou des hooks qui cassent le front ou le BO dès le premier autoload.

Le symptôme “classique” (BO inaccessible, page blanche, 500/503, maintenance bloquée, boucle de redirection) se diagnostique plus vite si vous forcez un découpage : runtime (PHP-FPM/Apache), app (PrestaShop/Symfony), données (MySQL), assets/cache (var/cache, Smarty, OPcache/CDN). Vous allez ensuite choisir une stratégie : rollback propre, reprise contrôlée de l’upgrade, ou réparation ponctuelle.

Un détail “terrain” qui fait gagner du temps : notez l’heure exacte du lancement et l’outil utilisé (zip + FTP, Git/CI, Autoupgrade, CLI). En pratique, sur beaucoup de boutiques (notamment en Europe/Paris, avec pics pendant soldes/Black Friday), l’enjeu n’est pas seulement “réparer”, mais éviter d’écrire dans une base à moitié migrée et documenter ce qui s’est passé pour le prochain upgrade.

Containment avant toute réparation : figer, sauvegarder, réduire la surface

Avant de “réparer”, vous devez empêcher les écritures et capturer l’état actuel. Sur une boutique en prod, la pire décision est de réactiver le front pour “tester” : vous créez des commandes/paniers dans une base potentiellement à moitié migrée. Activez le mode maintenance et, si vous êtes déjà en erreur 503, traitez-le d’abord côté infra (cf. diagnostic serveur dans l’article Diagnostic d’une Erreur HTTP 503 : logs et ressources).

Checklist “10 minutes” (prod) :

• Couper l’accès public (maintenance PrestaShop + éventuellement règle Nginx/Apache temporaire si le BO est KO).
• Suspendre les tâches automatisées qui écrivent : CRON (export, synchro ERP, relances e-mail), webhooks, imports produits.
• Noter la version visée (ex. 8.1.x → 8.2.x, ou 8.x → 9.x) + l’outil (Upgrade Assistant, déploiement CI, etc.).
• Vérifier rapidement l’espace disque et les inodes (df -h + df -ih) : une extraction incomplète du package d’upgrade par manque d’inodes est un grand classique.
• Faire au minimum un backup DB + fichiers avant toute tentative de relance.

Sauvegarde minimale exploitable : dump MySQL transactionnel + snapshot des fichiers. Pour MySQL/MariaDB (InnoDB), un dump cohérent se fait avec --single-transaction (évite un lock global sur InnoDB), à condition de ne pas inclure de tables MyISAM. Exemple :

# Pré-requis : accès SSH, utilisateur MySQL avec droits de lecture
mysqldump --single-transaction --routines --triggers \
  -u prestashop -p prestashop_db \
  | gzip -c > prestashop_db_$(date +%F_%H%M).sql.gz

# Snapshot fichiers (en excluant caches volumineux si besoin)
rsync -a --delete \
  --exclude='var/cache/' --exclude='app/cache/' --exclude='cache/' \
  /var/www/prestashop/ /backup/prestashop_files_$(date +%F_%H%M)/

Sur gros volumes, un snapshot LVM/ZFS est souvent plus fiable qu’un rsync long (risque de fichiers modifiés pendant la copie). Si vous êtes sur VPS/Docker, anticipez aussi l’espace disque : une extraction partielle du package d’upgrade par manque de disque/inodes est une cause fréquente.

Mini-scenario réaliste : la mise à jour est lancée via le module d’upgrade en pleine journée, l’extraction du zip s’arrête à 92% (disque plein), puis le module déclenche quand même une partie des migrations. Résultat : code “neuf” + DB “à moitié” + caches non purgés = page blanche sur front et BO. Dans ce cas, la priorité n’est pas de “vider var/cache”, mais de figer et récupérer un état restaurable.

Lire les logs là où ça casse : PHP, PrestaShop/Symfony, module d’upgrade

Le diagnostic “rapide” passe par les logs, pas par l’interface. Commencez côté serveur : logs PHP-FPM (/var/log/php*-fpm.log), Nginx/Apache (error log), et journal systemd si vous êtes en service managé. Les erreurs qui trahissent une mise à jour PrestaShop ratée sont souvent : Allowed memory size exhausted, Maximum execution time, Call to undefined function, Class not found, SQLSTATE[42S02] (table manquante) ou SQLSTATE[42S22] (colonne manquante).

Quelques commandes “sûres” pour aller droit au but (sans “toucher” au code) :

# Dernières erreurs Nginx/Apache
tail -n 200 /var/log/nginx/error.log
tail -n 200 /var/log/apache2/error.log

# PHP-FPM (chemin selon distro)
tail -n 200 /var/log/php8.2-fpm.log

# Suivre en direct pendant un refresh
tail -f /var/log/nginx/error.log

Côté application, sur PrestaShop 1.7/8/9 vous avez des logs Symfony/PrestaShop dans var/logs/ (selon version et configuration) et des logs consultables via le BO quand il est accessible. Si vous n’avez aucun log exploitable, mettez en place un suivi d’erreurs durable plutôt que de multiplier les “echo” : l’article sur le monitoring d’erreurs PrestaShop (PHP/MySQL/JS + alertes) donne une approche structurée.

Table de tri (symptôme → où regarder en premier) :

Symptôme	Indice typique	1er endroit à vérifier
Page blanche / 500 immédiat	Fatal error PHP, classe introuvable	logs PHP-FPM + error log web
503 après upgrade	pool PHP down, saturation RAM/CPU	journal systemd + logs FPM + ressources
BO OK, front KO	module/thème, override front	logs PrestaShop + désactivation modules front
SQLSTATE[42S02] / 42S22	migration DB incomplète	logs upgrade + état DB (tables/colonnes)
Redirections en boucle	.htaccess, SSL, cache, cookies	logs web + config URL + cache

Si vous êtes passé par Autoupgrade / Upgrade Assistant, cherchez aussi ses traces : le module écrit des journaux (et garde parfois des archives) qui indiquent exactement à quelle étape l’upgrade s’est interrompu (téléchargement, extraction, copie, mise à jour DB, nettoyage). Le dépôt officiel est public : dépôt Autoupgrade sur GitHub — vérifiez la version du module et son README plutôt que d’exécuter des scripts “trouvés sur un forum”.

Enfin, si vous devez vraiment reproduire le crash, faites-le hors prod et avec un debugger : Xdebug 3 + IDE vous fait gagner du temps sur les erreurs fatales dans un override/module. Référence : Installer et activer Xdebug 3 (CLI + web).

Bon réflexe : si vous activez temporairement le mode debug pour obtenir une stacktrace, faites-le sur une fenêtre très courte (et idéalement en IP-restrict) : une stacktrace peut exposer des chemins et versions.

Pannes “infra” pendant un upgrade : PHP incompatible, limites, droits, cache opcode

La mise à jour échoue très souvent avant même d’arriver à PrestaShop : PHP n’est pas compatible, une extension manque, ou les limites runtime explosent pendant l’extraction et les migrations. Si vous montez vers PrestaShop 9.x, ne partez pas du principe que “PHP à jour = OK” : la compatibilité exacte change vite, et la documentation n’est pas toujours cohérente. Gardez un tableau de compatibilité interne, et recoupez avec votre réalité serveur (voir PrestaShop 9 : versions PHP recommandées et incohérences de documentation).

Avant de relancer quoi que ce soit, vérifiez factuellement votre runtime :

• php -v (version CLI) et la version servie par PHP-FPM (via phpinfo() sur un endpoint protégé, ou en lisant la conf du pool).
• extensions utiles à PrestaShop/upgrade : zip, intl, gd/imagick (selon usage), pdo_mysql, curl, mbstring, openssl.
• timeouts côté reverse-proxy (Nginx) et côté PHP-FPM, qui peuvent tuer l’upgrade même si max_execution_time est élevé.

Pendant l’upgrade, montez temporairement des limites raisonnables (et redescendez ensuite). Typiquement :

• memory_limit : 512M à 1024M selon modules/catalogue,
• max_execution_time : 300s à 900s (ou mieux : exécution CLI),
• max_input_vars si des écrans BO post-upgrade cassent,
• post_max_size/upload_max_filesize si l’outil d’upgrade upload un zip.

Référence utile côté PHP : la configuration des erreurs et logs est documentée sur php.net – configuration des erreurs.

Vérifiez ensuite les droits et le propriétaire des fichiers : extraction faite par un utilisateur différent (FTP vs SSH vs process web) = mélange de permissions et échec de copie. Sur Linux, le pattern est trivial : www-data (ou user PHP-FPM) ne peut pas écrire dans var/, img/, modules/ ou translations/.

# Repérer rapidement des dossiers non inscriptibles par l'utilisateur courant
find var img modules themes translations -type d ! -writable 2>/dev/null | head -n 50

# Vérifier le propriétaire (à adapter à votre user/groupe)
stat -c "%U:%G %a %n" var | head

Dernier point souvent ignoré : OPcache et caches applicatifs. Après un upgrade, OPcache peut servir des anciens scripts si la configuration est agressive (timestamps) ou si le service PHP-FPM n’a pas été rechargé. En prod, ça se voit par des erreurs “fantômes” qui disparaissent après un reload. Le réglage d’OPcache en e-commerce mérite d’être intentionnel (article : PHP OPcache : paramètres recommandés pour optimiser les performances).

Point de méthode : ne mélangez pas “purge cache” et “réparation” au hasard. Exemple : supprimer var/cache est utile après avoir sécurisé code/DB, mais ça ne corrigera jamais une colonne manquante en base.

Conflits applicatifs : modules, overrides, thème, autoload Composer

Sur une boutique réelle, le cœur PrestaShop est rarement le seul suspect : ce sont les modules et overrides qui rendent une mise à jour PrestaShop fragile. Une signature très fréquente : tout “semblait” s’upgrader, puis un écran blanc arrive dès le premier hit parce qu’un module charge une classe supprimée/renommée, ou un override devient incompatible (méthode signature changée, type hints, services Symfony déplacés).

Pour isoler, on va au plus simple : désactiver en masse les modules non natifs et neutraliser les overrides, puis réactiver par lot. En base, vous pouvez couper les modules tiers sans BO (attention multiboutique) :

-- Désactiver un module précis
UPDATE ps_module SET active = 0 WHERE name = 'monmodule';

-- Désactiver tous les modules non natifs (approche brutale : à adapter)
UPDATE ps_module
SET active = 0
WHERE name NOT IN ('ps_emailalerts','ps_mainmenu','ps_facetedsearch');

-- Multiboutique : couper aussi l'association
UPDATE ps_module_shop ms
JOIN ps_module m ON m.id_module = ms.id_module
SET ms.enable_device = 0
WHERE m.name = 'monmodule';

Conseil opérationnel : faites une désactivation “intelligente” si vous avez des paiements/transporteurs. Sur beaucoup de boutiques françaises, couper d’un coup un module de paiement peut empêcher l’accès à des pages de commande ou casser le BO (ex. onglets ajoutés). La bonne approche est souvent : 1) repartir “minimal” (modules natifs essentiels + thème),
2) réactiver par lots (paiement/livraison d’abord),
3) terminer par les modules marketing/analytics.

Neutraliser les overrides se fait proprement en renommant le répertoire override/ (ex. override_OFF/) et en supprimant les index de classes en cache (selon version : var/cache/*/class_index.php ou équivalent). Ne supprimez pas “au hasard” : le but est de confirmer l’hypothèse override incompatible. Si la boutique repart sans overrides, vous avez une trajectoire claire : portage des overrides, ou remplacement par hooks/services.

Si votre déploiement utilise Composer (repo Git sans vendor/ ou pipeline CI), une mise à jour ratée peut être simplement un autoload incohérent : vendor/autoload.php absent, ou dépendances non installées. Le rappel est basique mais fatal : sur le site officiel, on lit : « Composer is a dependency manager for PHP. » (getcomposer.org). En pratique : exécutez un composer install --no-dev --optimize-autoloader sur l’artefact correct (et sur la bonne version de PHP), pas sur un mélange de branches.

Deux erreurs fréquentes en migration/upgrade :

• Installer des dépendances avec une version PHP différente de celle de la prod (ex. build en PHP 8.3, prod en 8.1) → dépendances/plateforme incohérentes.
• Mélanger un zip “release” (qui embarque parfois vendor/) avec un dépôt Git (où vendor/ est absent) → vous vous retrouvez avec des restes de dépendances.

Pour éviter les forks et distributions douteuses lors d’un upgrade, relisez votre provenance (zip officiel vs dépôt Git) et sécurisez la chaîne d’approvisionnement : PrestaShop GitHub : dépôts officiels, vérification et sécurité anti-forks.

Base MySQL en état hybride : migrations incomplètes, collations, incohérences

Quand le front/BO crashe avec des erreurs SQL (table not found, unknown column, duplicate key name, collation mismatch), c’est rarement “MySQL qui déconne” : ce sont des migrations interrompues ou un prérequis non respecté (engine, collation, version). Sur MySQL 8/MariaDB modernes, InnoDB est le standard et doit être cohérent partout ; la doc MySQL rappelle : « InnoDB is the default storage engine for MySQL. » (doc MySQL InnoDB). Si vous avez encore des tables MyISAM héritées, vous vous tirez une balle dans le pied pour la cohérence et les locks.

Commencez par qualifier l’état :

• La version “code” et la version “DB” sont-elles alignées ? (PrestaShop stocke des indicateurs en configuration ; le nom exact dépend des versions, donc vérifiez directement en base ce qui est présent dans ps_configuration.)
• Les scripts d’upgrade ont-ils été appliqués jusqu’au bout ? (souvent, un dernier “cleanup” n’a pas été exécuté mais la DB a déjà bougé.)
• Les collations/charsets ont-ils été uniformisés ? (les erreurs Illegal mix of collations surgissent après certains upgrades et sur des environnements hétérogènes.)

Quelques requêtes de qualification (à adapter au préfixe de vos tables) :

-- Repérer des tables qui ne sont pas en InnoDB
SELECT TABLE_NAME, ENGINE
FROM information_schema.TABLES
WHERE TABLE_SCHEMA = DATABASE()
  AND ENGINE <> 'InnoDB';

-- Repérer des collations différentes (source fréquente de "Illegal mix of collations")
SELECT TABLE_NAME, TABLE_COLLATION
FROM information_schema.TABLES
WHERE TABLE_SCHEMA = DATABASE()
ORDER BY TABLE_COLLATION, TABLE_NAME;

-- Lister des clés de configuration liées à la version / upgrade (noms variables selon versions)
SELECT name, value
FROM ps_configuration
WHERE name LIKE '%VERSION%'
   OR name LIKE '%UPGRADE%'
ORDER BY name;

Ensuite, évitez la tentation du “SQL correctif” improvisé en prod. La trajectoire robuste est : restaurer sur un environnement de staging, rejouer l’upgrade à blanc, puis seulement appliquer les corrections. Si votre base n’est pas en UTF-8 cohérent (utf8mb4 + collation modernisée), vous allez de toute façon replonger au prochain saut de version. Pour cadrer ce chantier, voir Prérequis système : migration MySQL vers MariaDB, InnoDB et collation UTF-8 : Prérequis MySQL / MariaDB.

Dernier point : même si vous “réparez” l’accès au BO, ne considérez pas la boutique comme saine tant que vous n’avez pas vérifié des parcours réels (création panier, checkout, génération facture, e-mails, recherche, facettes). Les migrations touchent parfois des index et des contraintes ; une boutique qui “s’affiche” peut rester fonctionnellement cassée (ex. recherche vide, stocks incohérents, règles paniers invalides).

Une astuce simple : après un upgrade interrompu, ciblez 2–3 fonctionnalités “sensibles” qui touchent beaucoup de tables (ex. facettes, règles panier, génération PDF). Ce sont souvent elles qui révèlent une DB hybride avant même que les commandes ne soient impactées.

Réparer vite : rollback, reprise de l’upgrade, ou bascule blue/green

Quand l’upgrade est raté, il y a trois stratégies, et elles ne sont pas équivalentes en risque.

1) Rollback (revenir à l’état exact pré-upgrade) : c’est l’option la plus sûre si vous avez un backup récent, et si vous pouvez accepter de perdre les écritures post-upgrade (d’où l’intérêt du containment). Le rollback “propre” consiste à restaurer à la fois la base et les fichiers (y compris img/, modules/, themes/, .htaccess, et le dossier admin), puis à purger caches et redémarrer PHP-FPM. Si vous avez besoin d’un plan opérationnel détaillé, l’article Migration PrestaShop 9 : sécurité, tests et plan de rollback est un bon canevas.

2) Reprise contrôlée de l’upgrade : pertinente si l’outil a échoué sur une étape identifiée (timeout pendant DB, extraction incomplète, permissions). Là, vous corrigez la cause (ex. passer en CLI, augmenter timeouts, libérer disque), puis vous relancez en vous appuyant sur les logs du module. Attention : relancer “en boucle” sans nettoyer (archives temporaires, caches, fichiers partiellement copiés) crée un état encore plus hybride.

3) Blue/Green : quand le downtime doit être minimal, et surtout quand la boutique est lourdement modifiée (beaucoup de modules, overrides, thème custom). L’idée : cloner (code + DB) vers un environnement green, upgrader et valider, puis basculer le trafic via DNS/LB. Ce n’est pas “du luxe” : c’est la seule manière de faire une migration/upgrade sans jouer la prod au casino. Référence sur la méthode : Migration PrestaShop : audit technique et plan incrémental blue/green.

Grille de décision rapide (quand vous avez 30 minutes pour trancher) :

• Vous avez un backup DB+fichiers récent et vérifié + la boutique a peut-être reçu des commandes pendant l’état hybride → rollback.
• Vous avez un log d’upgrade clair (“échec à l’étape X”) + cause évidente (droits, disque, timeout) + pas d’écritures après incident → reprise contrôlée.
• Boutique critique, forte complexité, contrainte d’indisponibilité → blue/green (même si ça prend plus de préparation, c’est souvent plus “court” en interruption).

Si vous êtes coincé entre rollback et réparation, posez un critère simple : si vous ne pouvez pas garantir l’intégrité des commandes, vous rollbackez. Une boutique e-commerce qui “tourne” mais qui génère des erreurs silencieuses (factures, mails, paiements) est pire qu’un downtime court.

Stabiliser le prochain upgrade : observabilité, CI, prérequis, hygiène de modules

Une mise à jour PrestaShop ratée est souvent un symptôme d’architecture : pas d’environnement de staging équivalent, pas de CI, pas d’inventaire module/override, pas de budget d’observabilité. Les correctifs “one shot” ne tiennent pas. Vous voulez des signaux : taux d’erreurs PHP (5xx), exceptions Symfony, latence DB, saturation CPU/RAM, et journaux applicatifs corrélables par release. Référence directe : PrestaShop monitoring et alertes.

Côté delivery, industrialisez : build reproductible (artefacts immuables), verrouillage des dépendances (Composer lock), et validation automatisée des modules. Pour la chaîne de confiance (provenance, SBOM, contrôles), vous avez un article orienté CI : CI PrestaShop : provenance, SBOM et validation automatique des modules. Ça réduit drastiquement les surprises du type “le module X n’est plus compatible avec Symfony/PrestaShop 9”.

Enfin, soyez brutal sur l’hygiène : modules obsolètes, overrides non testés, et thème non maintenu = upgrade à haut risque. Documentez un protocole de prérequis (PHP/extensions, MariaDB/MySQL, Elasticsearch si utilisé, droits fichiers), et exécutez des tests fonctionnels minimum (smoke tests checkout, création client, back-office).

Checklist pré-upgrade (staging) à conserver en interne :

• Inventaire modules (versions + compatibilité annoncée) et overrides (liste + criticité).
• Vérification runtime (version PHP-FPM réelle, extensions, limites, espace disque/inodes).
• Test de build (Composer) reproductible sur le même “type” d’environnement que la prod.
• Plan de purge caches (PrestaShop, OPcache, Redis/CDN) et plan de redémarrage contrôlé.
• Plan de rollback (DB + fichiers) et fenêtre de maintenance (inclure marge).

Si vous exploitez Redis/Varnish/CDN, planifiez explicitement les purges et le redémarrage contrôlé des services de cache (Redis : configurer Redis pour PrestaShop). Sur des boutiques à trafic, c’est souvent le détail qui fait la différence entre “upgrade propre” et “bugs fantômes” pendant des heures (contenu non à jour, sessions erratiques, assets obsolètes).

À ce stade, le but n’est pas d’éviter toute panne (ça n’existe pas), mais de rendre une mise à jour PrestaShop ratée réversible et diagnostiquable en minutes, pas en nuits blanches.