MySQL server has gone away : erreur de reconnexion à la base

Erreur de reconnexion à la base de données

En anglais : Error reconnecting to the database

Une page de WordPress s’interrompt avec le titre « Erreur de reconnexion à la base de données » et une explication : le contact avec le serveur de la base a été perdu. Dans le journal PHP, ou dans debug.log, vous trouvez plutôt une ligne comme « WordPress database error MySQL server has gone away for query … ». Le cas se présente surtout pendant les opérations longues (import, export, sauvegarde, tâche planifiée), mais aussi, par intermittence, sur un serveur surchargé.

Contrairement à l’erreur de connexion à la base de données, qui survient dès le démarrage, ici la connexion fonctionnait : elle a été coupée en cours de route.

Ce que signifie cette erreur

« MySQL server has gone away » est le texte de l’erreur 2006 renvoyée par MySQL ou MariaDB à PHP : le serveur a fermé la connexion, ou n’a pas répondu. Il ne s’agit pas d’une erreur de syntaxe SQL, et ce n’est pas non plus un manque de mémoire de PHP.

Dans wp-includes/class-wpdb.php, la méthode query() contrôle le code d’erreur après chaque requête. En cas d’erreur 2006 (commentaire « Database server has gone away, try to reconnect »), elle appelle check_connection(). Celle-ci envoie d’abord un petit test (DO 1) puis, s’il échoue, tente de se reconnecter jusqu’à reconnect_retries fois (5 par défaut), en attendant une seconde entre chaque essai. Si la reconnexion réussit, la requête est rejouée sans que vous ne voyiez rien.

Si les cinq essais échouent, WordPress affiche la page « Erreur de reconnexion à la base de données », avec le texte « Cela signifie que le contact avec le serveur de base de données à l’adresse … a été perdu. Cela peut signifier que le serveur de votre base de données ne fonctionne plus. » et deux questions : le serveur fonctionne-t-il, et n’est-il pas soumis à une charge particulièrement lourde ? Attention : si le hook template_redirect est déjà passé, il est trop tard pour afficher cette page. La fonction renvoie simplement false, et seule la ligne du journal trahit la coupure.

Une erreur voisine, « Lost connection to MySQL server during query » (code 2013), n’entre pas dans ce mécanisme de reprise : le code du cœur ne gère que le code 2006.

Diagnostic rapide

Symptôme / constat	Cause probable	À vérifier
L’erreur survient pendant un import ou l’insertion d’un gros contenu	Requête plus grande que max_allowed_packet	Journal MySQL : « Got a packet bigger than ’max_allowed_packet’ bytes »
Elle survient après une longue étape de calcul ou un appel API	Connexion inactive fermée par wait_timeout	SHOW VARIABLES LIKE 'wait_timeout';
Elle touche tout le site en même temps, par intermittence	MySQL redémarre ou plante	SHOW GLOBAL STATUS LIKE 'Uptime';, journal système (OOM)
Elle apparaît lors des pics de trafic	Trop de connexions, serveur saturé	max_connections, charge du serveur
Elle survient après une longue pause d’un script WP-CLI	Connexion fermée pendant l’inactivité	Découper la tâche, rouvrir la connexion
La base est distante (autre serveur)	Coupure réseau, pare-feu coupant les connexions inactives	Délais réseau et pare-feu entre les deux machines

Les causes les plus fréquentes

1. max_allowed_packet trop petit : une seule requête (ligne d’import, contenu avec images encodées, option géante) dépasse la taille maximale acceptée par le serveur. La valeur par défaut dépend de la version, de quelques Mo à 64 Mo.
2. wait_timeout trop court : MySQL ferme la connexion quand elle reste inactive plus longtemps que ce délai. Le défaut est de 28 800 secondes, mais certains hébergeurs le réduisent fortement.
3. Un redémarrage ou un plantage de MySQL, souvent provoqué par le gestionnaire de mémoire du noyau (OOM killer) quand le serveur manque de RAM.
4. Un processus tué par l’hébergeur ou par un administrateur (KILL), ou une limite de connexions atteinte.
5. Une coupure réseau entre le serveur web et une base distante.
6. Un traitement qui garde la connexion ouverte pendant un appel à une API externe lente ou un calcul lourd.

Solutions pas à pas

Avant de modifier la configuration de MySQL, sauvegardez la base (mysqldump -u UTILISATEUR -p NOM_DE_LA_BASE > sauvegarde.sql) et notez les valeurs actuelles. Du moins invasif au plus technique :

1. Lire le journal pour identifier la cause

Consultez le journal d’erreurs de MySQL juste après l’incident (le chemin dépend de votre système) et le journal de WordPress :

sudo tail -n 50 /var/log/mysql/error.log
sudo journalctl -u mariadb --since "1 hour ago"   # ou -u mysql
sudo dmesg | grep -i -E 'out of memory|killed process'

Une ligne « Got a packet bigger than ’max_allowed_packet’ bytes » désigne la taille des requêtes. « Aborted connection … (Got timeout reading communication packets) » évoque un délai d’inactivité. Un « Out of memory: Killed process … (mysqld) » indique une saturation mémoire. Pour savoir si MySQL a redémarré :

SHOW GLOBAL STATUS LIKE 'Uptime';
SHOW VARIABLES LIKE 'wait_timeout';
SHOW VARIABLES LIKE 'max_allowed_packet';

Un Uptime très bas signifie un redémarrage récent. Notre article MySQL server has gone away : l’erreur qui interrompt un import volumineux illustre le diagnostic complet.

2. Augmenter max_allowed_packet

Si les requêtes sont trop grosses, relevez la limite dans la configuration du serveur (par exemple /etc/mysql/my.cnf, ou un fichier de /etc/mysql/mariadb.conf.d/), dans la section [mysqld] :

[mysqld]
max_allowed_packet = 64M

Redémarrez ensuite le service (sudo systemctl restart mariadb ou mysql). Pour tester sans redémarrer, SET GLOBAL max_allowed_packet = 67108864; s’applique aux nouvelles connexions, mais ne survit pas à un redémarrage. Pour un import en ligne de commande, le client accepte aussi son propre réglage :

mysql --max-allowed-packet=256M -u UTILISATEUR -p NOM_DE_LA_BASE < sauvegarde.sql

3. Adapter wait_timeout ou raccourcir les traitements

Quand la connexion reste inactive trop longtemps, le plus robuste est de limiter l’inactivité côté application : découpez les traitements en lots, et ne gardez pas la connexion ouverte pendant un appel réseau. Dans votre propre code, vous pouvez vérifier ou rétablir la connexion avant une requête :

global $wpdb;
$wpdb->check_connection(); // tente la reconnexion si elle est tombée

Côté serveur, vous pouvez augmenter le délai (wait_timeout = 600 et interactive_timeout = 600 dans [mysqld]). Évitez toutefois les valeurs démesurées : elles laissent des connexions mortes occuper le serveur. Sur un mutualisé où vous ne pouvez pas modifier la configuration, procédez par lots plus petits. Le cas du client WP-CLI qui reste muet pendant un import se lit dans wp-cli qui se fige pendant l’import d’une base volumineuse.

4. Corriger le manque de mémoire du serveur

Si le noyau tue MySQL, la mémoire est insuffisante. Réduisez la consommation (innodb_buffer_pool_size adapté à la RAM, nombre de processus PHP-FPM raisonnable), ou augmentez la mémoire du serveur. L’article sur l’OOM killer et PHP-FPM explique comment le confirmer. Un serveur web qui lui aussi s’effondre peut renvoyer une erreur 502 ; une table abîmée par le plantage se répare avec la fiche tables endommagées.

5. Vérifier le réseau et les limites de l’hébergeur

Avec une base distante, vérifiez qu’aucun pare-feu ne coupe les connexions inactives, et que DB_HOST dans wp-config.php est correct. Contrôlez les limites de connexions simultanées (max_connections, ou max_user_connections chez certains hébergeurs). Sur un mutualisé, contactez le support en citant le message exact et l’heure de l’incident.

Sans accès à l’administration

Aucune de ces vérifications ne passe par l’administration de WordPress : utilisez SSH, phpMyAdmin (pour consulter SHOW VARIABLES) et le panneau de l’hébergeur. Pour activer le journal de WordPress, éditez wp-config.php par SFTP et ajoutez define( 'WP_DEBUG_LOG', true ); (avec WP_DEBUG à true), au-dessus de « That’s all, stop editing! ».

Prévenir l’erreur

• Dimensionnez max_allowed_packet en fonction de vos plus gros contenus et imports, avant la mise en production.
• Découpez les traitements longs (imports, exports, migrations) en lots courts, avec une reconnexion entre les lots.
• Surveillez la mémoire et la charge du serveur de base de données, et configurez des alertes sur les redémarrages inattendus.
• Évitez les appels réseau lents entre deux requêtes SQL dans le même traitement.
• Testez la résilience de vos extensions face à une base coupée ; voir l’article simuler une base de données coupée.

Questions fréquentes