Corriger une erreur Bad Gateway sur PrestaShop

L'erreur 502 Bad Gateway est l'un des problèmes les plus frustrants sur PrestaShop. Elle survient lorsque le serveur web (souvent Nginx) ne parvient pas à obtenir une réponse valide du processus PHP en arrière-plan. Les causes sont multiples, mais le diagnostic suit une logique méthodique.

Le code 502 signifie que le serveur frontal (Nginx, dans la plupart des environnements PrestaShop hébergés sur des serveurs dédiés ou VPS) a transmis la requête au serveur applicatif (PHP-FPM), mais que celui-ci n'a pas répondu correctement. Cela peut signifier que PHP a planté, a dépassé un délai d'exécution, ou que la communication entre les deux services est interrompue.

• PHP-FPM est arrêté ou surchargé (trop de processus simultanés)
• Le script PHP dépasse le délai d'exécution (max_execution_time)
• Les buffers Nginx sont trop petits pour les réponses de PrestaShop
• Un module PrestaShop génère une erreur fatale PHP
• La mémoire allouée à PHP est insuffisante (memory_limit)
• Un problème réseau entre Nginx et le socket PHP-FPM

Avant toute modification, consultez les logs. Le fichier error.log de Nginx et le log PHP-FPM contiennent presque toujours l'indice clé. Cherchez des messages comme « upstream timed out », « recv() failed » ou « broken pipe ».

# Logs Nginx
tail -f /var/log/nginx/error.log

# Logs PHP-FPM (chemin variable selon la distribution)
tail -f /var/log/php-fpm/error.log
tail -f /var/log/php8.1-fpm.log

PrestaShop génère souvent des réponses HTTP volumineuses, notamment sur les pages de listing produit ou dans le back-office. Si les buffers Nginx sont trop petits, la réponse ne passe pas et Nginx renvoie une 502. Ajoutez ou ajustez ces directives dans votre bloc server ou location :

# Dans le bloc server ou http de Nginx
proxy_buffer_size       128k;
proxy_buffers           4 256k;
proxy_busy_buffers_size 256k;

# Si vous utilisez fastcgi (PHP-FPM via socket)
fastcgi_buffer_size         128k;
fastcgi_buffers             4 256k;
fastcgi_busy_buffers_size   256k;
fastcgi_read_timeout        300;

Assurez-vous que PHP-FPM dispose de suffisamment de processus workers et de mémoire. Dans le fichier pool de PHP-FPM (souvent www.conf), vérifiez :

; Augmenter si nécessaire
pm.max_children = 30
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 10

; Délai d'exécution
request_terminate_timeout = 300

PrestaShop, surtout avec de nombreux modules et un catalogue volumineux, peut consommer beaucoup de mémoire. Vérifiez la valeur de memory_limit dans votre php.ini :

; php.ini
memory_limit = 512M
max_execution_time = 300

Certaines erreurs 502 ne surviennent que sur des requêtes Ajax spécifiques dans le back-office de PrestaShop (import produit, génération de statistiques, etc.). Dans ce cas, le problème est souvent lié au temps d'exécution. Augmentez les timeouts côté Nginx et PHP, et surveillez les logs pour identifier la requête exacte qui échoue.

Après chaque changement de configuration, redémarrez les services concernés et testez :

# Vérifier la syntaxe Nginx
nginx -t

# Redémarrer Nginx et PHP-FPM
systemctl restart nginx
systemctl restart php8.1-fpm

# Tester une page problématique
curl -I https://votre-site.fr/page-problematique