Erreur 503 sur Magento - Causes & solutions

Symptômes : comment confirmer le diagnostic

Avant de toucher quoi que ce soit, confirme que tu as bien affaire à une vraie 503 et pas à une 500 ou une page blanche. Ouvre les outils développeur du navigateur (onglet Réseau) ou interroge l'URL en ligne de commande pour lire le code HTTP réel renvoyé.

Le détail décisif : regarde à quoi ressemble la page d'erreur. Si elle est stylée aux couleurs de Magento (logo, mise en page Luma/Hyvä), c'est l'application qui répond — typiquement le flag de maintenance. Si la page est brute, grise, sans CSS ("503 Service Unavailable" en Times New Roman), c'est Nginx, Apache ou Varnish qui répond avant même d'atteindre Magento. Ce seul indice oriente tout le reste du diagnostic.

• Front office ET admin (`/admin`) renvoient 503 → cause globale (flag, serveur, Varnish), pas un module isolé.
• Page d'erreur stylée Magento → 503 applicative (flag de maintenance, le plus probable).
• Page brute non stylée → 503 serveur (PHP-FPM down, OOM, Varnish sans backend sain).
• Message exact "The server is temporarily unable to service your request due to maintenance downtime or capacity problems" → réponse Apache/Nginx standard.
• Message "Backend fetch failed" ou "No healthy backends" → Varnish ne joint pas l'application.
• 503 intermittente uniquement en pic de trafic → saturation PHP-FPM (`max_children`) ou base en deadlock, pas le flag.

# Code HTTP réel + en-têtes (repère Server: et Via: Varnish)
curl -sI https://ta-boutique.com/ | head -n 20

# Voir le corps de la page 503 sans le rendu navigateur
curl -s https://ta-boutique.com/ | head -n 40

Impact business immédiat

Une 503 n'est pas un bug d'affichage cosmétique : c'est un arrêt de chiffre d'affaires. Tant qu'elle dure, aucune commande ne passe, le coût d'acquisition de ton trafic payant part en fumée (tu paies des clics qui atterrissent sur une page morte) et tes clients fidèles repartent chez le concurrent.

Le risque le plus sous-estimé est SEO. Un 503 ponctuel est même recommandé par Google pour une vraie maintenance (il indique "reviens plus tard, garde l'index"). Mais un 503 qui s'éternise sur plusieurs heures, ou qui revient en boucle, finit par dégrader le crawl et peut faire chuter les positions de tes pages catalogue — l'effet se paie en revenus organiques pendant des semaines après la résolution.

• Downtime total : zéro commande tant que le front renvoie 503.
• Budget pub gaspillé : Google Ads et Meta continuent d'envoyer du trafic sur une boutique morte.
• Dégradation SEO si le 503 persiste ou se répète (perte de crawl, chute de positions).
• Perte de confiance : clients récurrents qui tombent sur l'erreur et ne reviennent pas.
• Effet domino sur l'admin : tu ne peux même plus passer de commandes manuelles ni gérer le SAV.

Causes classées par probabilité

Sur Magento 2.4.x, les causes d'une 503 se classent dans un ordre de fréquence assez stable. Attaque-les dans cet ordre, c'est statistiquement le chemin le plus rapide vers la résolution.

• 1. Flag de maintenance resté en place (le plus fréquent) — `var/.maintenance.flag` créé automatiquement pendant un `setup:upgrade` ou un déploiement, jamais retiré parce que la commande a planté ou timeout.
• 2. Mode maintenance activé volontairement et oublié — quelqu'un a lancé `maintenance:enable` et n'a pas désactivé.
• 3. Varnish sans backend sain — "No healthy backends" / "Backend fetch failed" quand PHP-FPM ou l'application ne répond pas au probe Varnish.
• 4. PHP-FPM saturé — `max_children` atteint en pic de trafic, plus aucun worker disponible, le serveur web renvoie 503.
• 5. Manque de ressources / disque plein — `/var` rempli par `var/log` ou `var/cache`, OOM kill du process PHP.
• 6. Base de données non upgradée — "Please upgrade your database" après une mise à jour de code sans `setup:upgrade`.
• 7. setup:upgrade ou setup:di:compile interrompu — déploiement à moitié appliqué, flag posé mais code incohérent.
• 8. Permissions de fichiers — flag recréé par root, non supprimable par l'utilisateur web (`www-data`).

Diagnostic : les commandes à lancer

Connecte-toi en SSH à la racine Magento (le dossier qui contient `bin/magento`, `app/`, `var/`). L'objectif : savoir si c'est applicatif ou serveur, et lire le vrai message d'erreur avant d'agir.

Première chose, vérifie l'état officiel du mode maintenance plutôt que de deviner — Magento te le dit directement :

1. Vérifie l'état du mode maintenance et la présence du flag.
2. Lis les logs applicatifs Magento (system, exception, reports).
3. Lis les logs serveur (Nginx/Apache, PHP-FPM) pour les 503 brutes.
4. Si Varnish est en place, vérifie l'état des backends.
5. Si erreur DB, contrôle l'état du schéma.

# Réponse Magento officielle
php bin/magento maintenance:status

# Le flag M2 est CACHE (point devant) dans var/
ls -la var/.maintenance.flag 2>/dev/null && echo "FLAG PRESENT"
# Liste aussi var/.maintenance.ip s'il existe (allowlist)
ls -la var/.maintenance.* 2>/dev/null

# Erreurs applicatives en direct pendant l'incident
tail -n 100 var/log/exception.log
tail -n 100 var/log/system.log

# Reports d'erreur fatale (l'ID affiché sur la page d'erreur Magento)
ls -lt var/report/ | head
cat var/report/ID_AFFICHE_SUR_LA_PAGE

# Filtrer les 503 / database upgrade
grep -i "upgrade your database\|maintenance\|503" var/log/*.log | tail -n 30

# Nginx
tail -n 50 /var/log/nginx/error.log
# Apache (selon distrib)
tail -n 50 /var/log/apache2/error.log /var/log/httpd/error_log 2>/dev/null
# PHP-FPM : 'max_children reached' = saturation workers
tail -n 50 /var/log/php-fpm/error.log /var/log/php*-fpm.log 2>/dev/null
grep -i "max_children\|out of memory\|killed" /var/log/php*-fpm*.log 2>/dev/null

# Disque plein ? (cause silencieuse fréquente de 503 en cascade)
df -h
du -sh var/log var/cache var/page_cache 2>/dev/null

# Liste les backends et leur santé (Sick = KO -> 503 'No healthy backends')
varnishadm backend.list
# Logs Varnish en direct, filtrés sur les 503
varnishlog -q "RespStatus == 503" -d | head -n 60

# Magento te dit si le schéma/data est à jour
php bin/magento setup:db:status

# Au besoin, inspection directe du flag de version
mysql -u UTILISATEUR -p BASE -e "SELECT * FROM setup_module LIMIT 5;"

Solutions pas-à-pas

Applique le scénario qui correspond à ton diagnostic. Ne saute pas l'étape de vérification : supprimer le flag pendant qu'un `setup:upgrade` tourne encore casse la boutique pour de bon.

1. Cas n°1 — Flag de maintenance fantôme (le plus courant). D'abord confirme qu'AUCUN upgrade n'est en cours (`ps aux | grep magento`). Ensuite désactive proprement plutôt que de supprimer à la main : `php bin/magento maintenance:disable`. Si la commande échoue ou si tu n'as pas le CLI, supprime le fichier : `rm -f var/.maintenance.flag` (Magento 2). Re-vérifie : `php bin/magento maintenance:status`.
2. Vide le cache après suppression du flag : `php bin/magento cache:flush` (vide aussi le stockage Varnish/Redis) puis si besoin `php bin/magento cache:clean`. Recharge le front en navigation privée pour éviter un faux positif de cache navigateur.
3. Cas n°2 — Voir l'erreur réelle masquée. Si la page affiche "Exception printing is disabled by default for security reasons", passe temporairement en mode développeur : `php bin/magento deploy:mode:set developer`, recharge, lis l'erreur affichée, corrige, puis reviens en production : `php bin/magento deploy:mode:set production`. Ne laisse JAMAIS le mode développeur en prod.
4. Cas n°3 — Erreur DB ("Please upgrade your database"). Mets le site en maintenance volontaire, lance la mise à jour du schéma, attends qu'elle se termine VRAIMENT, puis désactive : `php bin/magento maintenance:enable` → `php bin/magento setup:upgrade` → `php bin/magento setup:di:compile` (si nécessaire) → `php bin/magento maintenance:disable`.
5. Cas n°4 — Varnish 'No healthy backends'. Le backend (PHP-FPM/app) est down ou ne répond pas au probe. Redémarre PHP-FPM (`systemctl restart php-fpm` ou `php8.x-fpm`), vérifie `varnishadm backend.list` jusqu'à voir `Healthy`, puis recharge Varnish si la config a changé.
6. Cas n°5 — PHP-FPM saturé (503 en pic). Augmente `pm.max_children` dans le pool FPM en fonction de la RAM disponible, vérifie qu'aucun script long ne monopolise les workers, puis `systemctl restart php-fpm`. Surveille avec `tail -f` le retour à la normale.
7. Cas n°6 — Disque plein. Libère `/var` : purge les vieux logs et reports, vide le cache disque, puis seulement après diagnostic relance `php bin/magento setup:di:compile`. Ne supprime jamais `var/` entier en aveugle.
8. Permissions du flag récalcitrant. Si `rm` renvoie "Operation not permitted", le flag appartient à root : `sudo rm -f var/.maintenance.flag` puis recale les droits : `chown -R www-data:www-data var/` (adapte l'utilisateur web à ton serveur).

# Bonne syntaxe : DOUBLE tiret --ip= (les concurrents copient un tiret cassé)
php bin/magento maintenance:enable --ip=192.0.2.20 --ip=192.0.2.21
# Tu vois le site, les visiteurs ont le 503
php bin/magento maintenance:status
# Retirer l'allowlist et rouvrir à tous
php bin/magento maintenance:disable

ps aux | grep -E "setup:upgrade|setup:di:compile|bin/magento" | grep -v grep
# Verrou cron setup ? S'il existe et qu'un process tourne, NE supprime PAS le flag
ls -la var/.setup_cronjob_status 2>/dev/null

Spécificités par version

Le piège n°1, recopié partout sur le web, c'est l'emplacement du flag. Il diffère selon la version majeure et une erreur d'orthographe te fait perdre un temps précieux.

Sur Magento 2.x, le flag est un fichier CACHÉ (point devant) dans le dossier `var/` : `var/.maintenance.flag`. Beaucoup de tutoriels écrivent `var/maintenance.flag` sans point — c'est faux pour Magento 2, tu ne trouveras jamais le fichier. Sur Magento 1.x, c'est `maintenance.flag` (sans point) directement à la racine.

Magento 1 est en fin de vie (EOL juin 2020) : pas de CLI `bin/magento`, donc pas de `maintenance:disable` — la seule option est de supprimer le fichier à la main. Si tu es encore sur Magento 1, la 503 est un signal de plus pour migrer.

• Magento 2.4.x (Open Source / Adobe Commerce) : flag = `var/.maintenance.flag` (avec point). CLI complet disponible (`maintenance:enable/disable/status`).
• Magento 1.x (EOL) : flag = `maintenance.flag` (sans point) à la racine. Pas de CLI, suppression manuelle uniquement.
• Adobe Commerce Cloud / Magento Cloud : pas d'accès SSH libre à `var/` en prod managée — voir la section dédiée ci-dessous. Une 503 peut venir d'un timeout upstream entre Fastly (CDN/cache) et l'application.
• Varnish : utilisé massivement sur Magento 2 en production. Les 503 "Backend fetch failed" sont spécifiques à cette couche et absentes de Magento 1.

Cas particulier : hébergement managé (Adobe Commerce Cloud, plateformes gérées)

Sur du Magento Cloud ou un hébergeur managé, tu n'as pas toujours un accès SSH brut au dossier `var/` de production, et le cache front est servi par Fastly (pas Varnish auto-hébergé). La logique change.

Dans ce cas, passe par le CLI fourni par la plateforme (par exemple `magento-cloud ssh` puis les commandes `bin/magento` habituelles, ou le panneau d'administration de l'hébergeur). Si la 503 vient d'un déploiement, regarde d'abord les logs de build/deploy de la plateforme avant de toucher au flag — sur Cloud, le mode maintenance est piloté par le pipeline de déploiement, pas par un simple `rm`.

• Utilise le CLI de la plateforme (`magento-cloud ssh`, console hébergeur) plutôt que de chercher `var/` à la main.
• Consulte les logs de déploiement managés : une 503 post-deploy y est souvent expliquée.
• Fastly remplace Varnish : une 503 peut être un timeout upstream Fastly → application. Vérifie la santé de l'app avant de purger Fastly.
• Ne force pas la suppression du flag pendant un build automatisé : laisse le pipeline finir.

Prévention : empêcher la 503 de revenir

La 503 récurrente a presque toujours la même origine mécanique : un `setup:upgrade` qui dépasse le `max_execution_time` PHP, plante en plein milieu, laisse le flag posé et un schéma à moitié migré. Pour éviter ça, ne lance jamais d'upgrade en pleine journée et donne-lui le temps de finir.

Côté serveur, le couple gagnant est : surveillance du disque (`/var` plein = 503 en cascade), dimensionnement de `pm.max_children` selon ta RAM, et un probe Varnish correctement configuré pour ne pas marquer le backend Sick au moindre hoquet.

• Lance `setup:upgrade` en maintenance volontaire et hors heures de pointe, jamais à chaud sur la prod.
• Augmente `max_execution_time` PHP côté CLI pour éviter le timeout en plein upgrade.
• Mets une alerte disque sur `/var` (logs et cache qui gonflent) avant qu'il sature.
• Dimensionne `pm.max_children` PHP-FPM en fonction de la RAM réelle (RAM dispo / mémoire moyenne par worker).
• Après chaque déploiement, vérifie systématiquement `maintenance:status` et `setup:db:status`.
• Garde une routine de purge des vieux `var/report/` et `var/log/`.

Quand appeler un expert

Tu peux gérer seul un flag fantôme ou un cache à vider. Appelle un expert quand le 503 persiste après suppression du flag, quand Varnish reste sur "No healthy backends" malgré le redémarrage de PHP-FPM, ou quand un `setup:upgrade` s'est interrompu et a laissé ta base dans un état incohérent — là, un mauvais geste peut corrompre le schéma et te coûter bien plus qu'une heure de downtime.

Si ta boutique est encore down et que le diagnostic ci-dessus pointe vers la base, Varnish ou un déploiement cassé, BugRescue (Soulaimane Aattar, expert Magento) intervient sur ce type d'incident : diagnostic des logs, remise en ligne propre et sécurisation du déploiement pour que la 503 ne revienne pas.

FAQ