Erreur de connexion à la base de données WordPress : le diagnostic dans l’ordre

Votre site affiche une page blanche avec une seule phrase : « Erreur lors de la connexion à la base de données ». Pas de menu, pas d’admin, rien. Le réflexe habituel, c’est d’aller changer le mot de passe de la base au hasard, et de découvrir une heure plus tard que le problème venait d’ailleurs.

Ce qui suit, c’est la procédure dans l’ordre, du plus fréquent au plus rare. Et ça commence par une étape que presque tous les tutoriels sautent : WordPress affiche trois messages d’erreur différents pour trois problèmes différents, et lire le bon vous fait gagner la plus grosse partie du temps de diagnostic.

Avant toute manipulation : sauvegardez les fichiers et la base de données si vous y avez encore accès. Rien de ce qui suit n’est destructeur, mais on ne touche jamais à une base sans filet.

Étape 0 : lisez le message exact, il désigne le coupable

J’ai vérifié ces trois chaînes directement dans le code de WordPress 7.1, dans wp-includes/class-wpdb.php et wp-includes/functions.php. Elles sortent d’endroits différents du cœur, et chacune veut dire une chose précise.

« Erreur lors de la connexion à la base de données » (souvent cité « Erreur lors de l’établissement d’une connexion à la base de données » dans les tutoriels, et Error establishing a database connection en anglais). WordPress n’a pas réussi à ouvrir la connexion. Soit les identifiants sont faux, soit le serveur MySQL ne répond pas. C’est le cas le plus courant, et celui que traite le gros de cet article.

« Impossible de sélectionner la base données » (la coquille est dans la traduction officielle, ne cherchez pas). Message très différent et beaucoup plus précis : la connexion au serveur a réussi. Vos identifiant et mot de passe sont donc bons. Ce qui coince, c’est la base elle-même : le nom dans DB_NAME ne correspond à aucune base existante, ou l’utilisateur n’a pas les droits dessus. Si vous voyez celui-là, ne perdez pas une seconde sur le mot de passe.

La traduction française de ce message se contredit d’ailleurs : elle annonce un serveur « pas connecté », puis confirme dans la même phrase que vos identifiant et mot de passe sont corrects. C’est la parenthèse qui dit vrai.

« One or more database tables are unavailable. The database may need to be repaired. » Sa version française existe (« Une ou plusieurs tables de votre base de données sont indisponibles »), mais il s’affiche parfois en anglais : à ce stade, WordPress n’a pas encore chargé la langue choisie dans les réglages. Il vient de is_blog_installed() et signifie que la connexion fonctionne mais que des tables manquent ou sont illisibles. Sautez directement à la section réparation.

Le détail que tout le monde rate : l’admin en dit plus que la page d’accueil

Regardez la fonction dead_db() dans wp-includes/functions.php. Elle contient ce commentaire dans le cœur : « If installing or in the admin, provide the verbose message. Otherwise, be terse. »

Traduction pratique : votre page d’accueil affiche la version courte, votre /wp-admin/ affiche la version détaillée. Sur le site public, les trois cas s’affichent d’ailleurs le plus souvent sous le même titre court, « Erreur lors de la connexion à la base de données ». Allez chercher l’erreur complète côté administration, c’est elle qui fait la différence. C’est gratuit et ça évite de deviner.

Côté public, voici tout ce que la panne laisse voir :

Deuxième cadeau du cœur, dans class-wpdb.php : le message long affiche la valeur réelle de DB_HOST telle que WordPress l’a lue. Vous voyez donc noir sur blanc à quel serveur il a essayé de parler. Si vous y lisez localhost alors que votre hébergeur vous a donné une adresse dédiée, votre diagnostic est terminé.

La même panne vue depuis /wp-admin/ : l’hôte lu dans DB_HOST apparaît en toutes lettres.

Un cas particulier avant d’aller plus loin : si vous tombez sur une jolie page d’erreur personnalisée aux couleurs de votre hébergeur, cherchez un fichier wp-content/db-error.php. Ce fichier est un drop-in, un fichier que WordPress charge à la place de son propre affichage. Certains hébergeurs en déposent un. Il remplace le message du cœur et vous prive donc de toutes les informations ci-dessus. Renommez-le temporairement pour retrouver le vrai message.

Étape 1 : les quatre lignes de wp-config.php

Ouvrez wp-config.php à la racine du site, par FTP ou par le gestionnaire de fichiers de votre hébergeur. Quatre constantes vous intéressent :

define( 'DB_NAME', 'nom_de_la_base' );
define( 'DB_USER', 'utilisateur' );
define( 'DB_PASSWORD', 'mot_de_passe' );
define( 'DB_HOST', 'localhost' );

Ce que je vérifie, dans cet ordre :

• Un espace parasite à l’intérieur des guillemets. Un copier-coller depuis un e-mail en glisse un facilement, et il est invisible à l’œil.
• Un caractère spécial dans le mot de passe. Une apostrophe simple non échappée casse la ligne PHP et provoque une erreur avant même la connexion.
• La valeur de DB_HOST. localhost est la valeur par défaut, mais certains hébergeurs, mutualisés comme infogérés, imposent une adresse spécifique, parfois avec un port du type mon-serveur.hebergeur.net:3306.
• Le fichier a-t-il été modifié récemment ? Si la panne suit une mise à jour, une migration ou une restauration de sauvegarde, la cause est presque toujours là.

Les bonnes valeurs se retrouvent dans l’espace client de votre hébergeur, section bases de données. Ne les devinez pas, allez les lire.

Étape 2 : le test qui tranche entre identifiants et serveur

C’est l’étape qui fait gagner le plus de temps, et c’est celle que je vois le moins souvent conseillée. Elle répond à une seule question : est-ce que le problème vient de vos identifiants, ou du serveur MySQL ?

Créez un fichier test-db.php à la racine du site, avec vos vraies valeurs :

<?php
// Test de connexion isolé, hors de WordPress.
// Depuis PHP 8.1, sans cette ligne, un échec lève une exception au lieu d'afficher le code.
mysqli_report( MYSQLI_REPORT_OFF );
$link = @mysqli_connect( 'localhost', 'utilisateur', 'mot_de_passe', 'nom_de_la_base' );

if ( ! $link ) {
    echo 'Echec : ' . mysqli_connect_errno() . ' - ' . mysqli_connect_error();
} else {
    echo 'Connexion OK, serveur MySQL ' . mysqli_get_server_info( $link );
}

Appelez-le dans le navigateur, puis lisez le numéro d’erreur. Il vaut de l’or :

• 1045 (Access denied) : identifiant ou mot de passe refusé. Le serveur va bien, vos identifiants sont faux. Régénérez le mot de passe depuis l’espace client et reportez-le dans wp-config.php.
• 1049 (Unknown database) : le serveur répond, mais la base nommée n’existe pas. Erreur de DB_NAME, ou base supprimée.
• 1044 (Access denied … to database) : l’identifiant est accepté, mais l’accès à cette base est refusé. Soit l’utilisateur n’a pas de droits dessus, soit le nom dans DB_NAME est faux : sur une base qu’il ne peut pas voir, MySQL répond souvent 1044 plutôt que 1049. Associez l’utilisateur à la base depuis l’espace client.
• 2002 ou 2003 (Can’t connect) : personne ne répond à l’adresse indiquée. Soit DB_HOST est faux, soit le serveur MySQL est à terre.
• 1203 ou 1040 (too many connections) : le serveur est debout mais sature. Voir la section suivante.

Supprimez ce fichier dès que vous avez la réponse. Il contient vos identifiants de base en clair et n’a rien à faire sur un site accessible publiquement.

Étape 3 : l’erreur qui va et vient n’a jamais la même cause

Voilà le tri le plus utile de tout l’article, et il tient en une observation.

Si l’erreur est permanente, le site est cassé tant qu’on n’y touche pas : identifiants, nom de base ou hôte. Étapes 1 et 2, et vous avez votre coupable.

Si l’erreur va et vient, le site tombe aux heures de pointe puis revient tout seul : ce n’est presque jamais la configuration. Un mot de passe ne se répare pas spontanément à 3 h du matin. Vous êtes sur un problème de charge, et les suspects sont peu nombreux :

• Le quota de connexions simultanées est atteint (max_user_connections). Classique en mutualisé quand le trafic monte ou qu’une extension ouvre des connexions sans les fermer.
• Un voisin bruyant sur le même serveur mutualisé qui sature MySQL pour tout le monde. Vous n’y pouvez rien, sauf changer d’offre.
• Des requêtes lentes qui s’empilent : une extension mal écrite, une table de logs devenue énorme, un import en arrière-plan.

Dans ce cas, arrêtez le diagnostic technique et ouvrez un ticket chez votre hébergeur en lui donnant les horaires précis des coupures. Lui seul voit les journaux MySQL. Si la réponse est « votre offre est trop juste », c’est un vrai signal : le prix d’un hébergement se juge sur ce genre de plafond, pas sur la promesse d’illimité de la page de vente. En parallèle, une passe sur l’optimisation des performances du site réduit mécaniquement le nombre de requêtes envoyées à la base.

Étape 4 : réparer des tables corrompues

On n’arrive ici que si la connexion passe (test de l’étape 2 concluant) mais que WordPress se plaint de tables indisponibles. Une coupure de courant pendant une écriture, un disque saturé ou un arrêt brutal de MySQL suffisent à abîmer une table.

WordPress embarque un outil de réparation, mais il est verrouillé par défaut. La condition est posée ligne 28 de wp-admin/maint/repair.php : sans la constante, la page refuse de s’exécuter. Ajoutez donc dans wp-config.php, au-dessus de la ligne /* C'est tout, ne touchez pas à ce qui suit */ :

define( 'WP_ALLOW_REPAIR', true );

Tant que la constante manque, la page de réparation affiche elle-même la ligne à ajouter :

Puis appelez https://votre-site.fr/wp-admin/maint/repair.php. La page s’affiche sans authentification, c’est pour cette raison qu’elle est verrouillée. Cliquez sur « Réparer la base de données », ou sur « Réparer et optimiser la base de données » si le site est déjà à l’arrêt : l’optimisation prend plus de temps et verrouille la base pendant l’opération.

Retirez la ligne dès que c’est terminé. WordPress vous le demande lui-même à la fin de l’opération, et ce n’est pas une politesse : tant qu’elle est là, n’importe qui peut lancer des opérations sur votre base sans être connecté.

Si vous avez un accès SSH, WP-CLI fait la même chose en deux commandes, et donne un rapport table par table :

# Diagnostic seul, ne modifie rien.
wp db check

# Réparation effective, après sauvegarde.
wp db repair

Un mot d’honnêteté : la réparation automatique ne récupère pas tout. Sur une table gravement abîmée, elle rend le site fonctionnel en perdant les lignes illisibles. Et sur les tables InnoDB, le moteur par défaut des installations récentes, la commande de réparation n’est tout simplement pas prise en charge : le rapport l’indique table par table. C’est exactement le moment où l’on est content d’avoir une sauvegarde récente, et où l’on comprend pourquoi la maintenance régulière d’un site n’est pas une dépense décorative.

Ce que ce n’est pas

Deux confusions me reviennent souvent, et elles font perdre des heures.

Une page entièrement blanche, sans aucun texte, n’est pas cette erreur. Là, c’est PHP qui s’est arrêté avant d’afficher quoi que ce soit : extension fautive, mémoire insuffisante, erreur fatale. Le diagnostic passe par les journaux PHP, pas par la base.

Un site qui s’affiche mal ou redirige vers la mauvaise adresse n’est pas cette erreur non plus. La base répond parfaitement dans ce cas, ce sont les valeurs siteurl et home de la table des options qui sont fausses. Ça arrive typiquement après une migration. Même chose si WordPress vous propose soudain de l’installer : la base répond, mais il ne trouve aucune table avec le préfixe indiqué par $table_prefix dans wp-config.php.

Le repère simple : si vous lisez une phrase d’erreur qui parle de base de données, vous êtes au bon endroit. Si vous ne lisez rien du tout, vous êtes ailleurs.

Quand arrêter et appeler l’hébergeur

Je fixe la limite à trois signaux. Le test de l’étape 2 renvoie 2002 ou 2003 alors que vos valeurs sont vérifiées dans l’espace client. Ou l’erreur va et vient sans que vous ayez rien changé. Ou plusieurs sites hébergés au même endroit tombent en même temps.

Dans ces trois cas, le problème est côté serveur et vous ne le réglerez pas depuis wp-config.php. Continuer à bricoler ne fera qu’ajouter des variables. Ouvrez un ticket avec le message exact, le code d’erreur mysqli, l’heure des coupures, et vous serez traité en quinze minutes au lieu de trois échanges.

Le résumé qui tient sur un post-it

Lisez le message exact et allez le chercher dans /wp-admin/ si la page publique est avare. Vérifiez les quatre constantes de wp-config.php en traquant l’espace parasite. Lancez le test mysqli isolé et notez le code d’erreur, il désigne le coupable en une seconde. Réparez les tables seulement si le message parle de tables, et retirez WP_ALLOW_REPAIR derrière vous.

Et si je ne devais garder qu’un conseil : notez si l’erreur est permanente ou intermittente avant de toucher à quoi que ce soit. Cette seule observation vous envoie dans la bonne moitié de l’article, et elle vous évite de changer un mot de passe qui n’a jamais été en cause.