PHP/MySQL : corriger l’erreur « Headers and client library mismatch »

Après une mise à jour de MySQL, MariaDB, PHP ou des extensions PHP, certaines applications anciennes peuvent afficher un avertissement de ce type :

PHP Warning: mysql_connect(): Headers and client library minor version mismatch.
Headers:50535 Library:50617Langage du code : CSS (css)

Ce message indique que l’extension PHP utilisée pour se connecter à MySQL a été compilée avec une version de headers différente de la bibliothèque cliente réellement chargée au moment de l’exécution.

En 2026, le point important est surtout celui-ci : si votre application utilise encore mysql_connect(), le problème n’est pas seulement une bibliothèque MySQL incohérente. Le vrai problème, c’est que le code utilise une API PHP supprimée depuis longtemps.

La correction moderne consiste donc à passer à mysqli ou PDO_MySQL, puis à vérifier que PHP utilise bien MySQL Native Driver, aussi appelé mysqlnd.

Pourquoi cette erreur apparaît ?

Historiquement, les extensions PHP de connexion à MySQL pouvaient utiliser la bibliothèque cliente MySQL, souvent appelée libmysqlclient. Si PHP était compilé contre une version, mais chargeait une autre version au runtime, l’avertissement Headers and client library minor version mismatch pouvait apparaître.

Ce problème concernait surtout les anciens environnements PHP 5.x, les mélanges de dépôts, les upgrades MySQL/MariaDB partiels, les paquets tiers, ou les serveurs qui avaient plusieurs versions de bibliothèques MySQL installées.

En 2026, sur une pile PHP moderne, la bonne réponse n’est pas de bricoler libmysqlclient. PHP fournit depuis longtemps MySQL Native Driver, mysqlnd, qui remplace l’ancienne bibliothèque cliente MySQL pour les extensions PHP MySQL. Le manuel PHP précise que mysqlnd est un remplacement de MySQL Client Library et qu’il fait partie des sources officielles de PHP depuis PHP 5.3.0.

mysql_connect() est supprimé depuis PHP 7

Le message d’origine mentionne mysql_connect(). C’est un énorme indice : l’application utilise l’ancienne extension mysql.

Cette extension a été dépréciée en PHP 5.5, puis supprimée en PHP 7.0. Le manuel PHP recommande d’utiliser mysqli ou PDO_MySQL à la place.

Donc, si vous voyez encore mysql_connect(), le code est incompatible avec PHP moderne. Sur PHP 7, PHP 8, PHP 8.4 ou PHP 8.5, la fonction n’existe plus.

La correction durable consiste à remplacer l’ancien code :

$link = mysql_connect( 'localhost', 'user', 'password' );
mysql_select_db( 'database', $link );

$result = mysql_query( 'SELECT * FROM posts', $link );Langage du code : PHP (php)

par mysqli ou, mieux encore pour beaucoup de projets modernes, par PDO.

Solution moderne avec PDO_MySQL

Voici un exemple minimal avec PDO :

$dsn = 'mysql:host=localhost;dbname=database;charset=utf8mb4';

$pdo = new PDO(
    $dsn,
    'user',
    'password',
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
        PDO::ATTR_EMULATE_PREPARES => false,
    ]
);

$stmt = $pdo->query( 'SELECT * FROM posts' );
$rows = $stmt->fetchAll();Langage du code : PHP (php)

PDO permet d’utiliser des requêtes préparées, une gestion d’erreurs propre, et une API stable. Pour une application ancienne à migrer, c’est souvent le meilleur choix.

Exemple avec requête préparée :

$stmt = $pdo->prepare( 'SELECT * FROM users WHERE email = :email' );
$stmt->execute(
    [
        'email' => $email,
    ]
);

$user = $stmt->fetch();Langage du code : PHP (php)

Solution moderne avec mysqli

Si vous préférez rester proche de l’ancien style MySQL, mysqli peut être plus rapide à adopter :

$mysqli = mysqli_connect( 'localhost', 'user', 'password', 'database' );

if ( ! $mysqli ) {
    throw new RuntimeException( mysqli_connect_error() );
}

mysqli_set_charset( $mysqli, 'utf8mb4' );

$result = mysqli_query( $mysqli, 'SELECT * FROM posts' );

while ( $row = mysqli_fetch_assoc( $result ) ) {
    // Traiter la ligne.
}Langage du code : PHP (php)

Et avec une requête préparée :

$stmt = mysqli_prepare( $mysqli, 'SELECT * FROM users WHERE email = ?' );
mysqli_stmt_bind_param( $stmt, 's', $email );
mysqli_stmt_execute( $stmt );

$result = mysqli_stmt_get_result( $stmt );
$user   = mysqli_fetch_assoc( $result );Langage du code : PHP (php)

Le manuel PHP précise que mysqli a été introduit avec PHP 5.0, et que MySQL Native Driver est inclus depuis PHP 5.3.

Installer l’extension PHP MySQL moderne sous Ubuntu ou Debian

Sur Debian, Ubuntu et distributions dérivées, l’extension MySQL moderne s’installe généralement avec le paquet php-mysql, ou avec un paquet versionné si vous gérez plusieurs versions PHP.

Pour la version PHP par défaut du système :

sudo apt update
sudo apt install php-mysql

Pour une version précise, adaptez le numéro :

sudo apt install php8.4-mysqlLangage du code : CSS (css)

ou, selon votre serveur :

sudo apt install php8.5-mysqlLangage du code : CSS (css)

Le nom exact dépend de votre distribution et de vos dépôts PHP. Sur un serveur avec plusieurs versions PHP, vérifiez la version réellement utilisée par le site avant d’installer l’extension.

Sur les paquets PHP modernes, mysqli et pdo_mysql utilisent normalement mysqlnd. Le manuel PHP rappelle que mysqlnd n’est pas une nouvelle API : les API restent mysqli et PDO_MySQL, qui peuvent utiliser ses services pour communiquer avec MySQL.

Vérifier que PHP utilise mysqlnd

Vérifiez d’abord les modules PHP chargés en CLI :

php -m | grep -Ei 'mysql|mysqli|pdo'Langage du code : JavaScript (javascript)

Vous devriez voir quelque chose comme :

mysqli
mysqlnd
PDO
pdo_mysql

Vérifiez ensuite les informations détaillées :

php -i | grep -Ei 'mysqlnd|Client API|pdo_mysql|mysqli'Langage du code : JavaScript (javascript)

Si vous utilisez PHP-FPM, ne vous contentez pas de la CLI. Le site peut utiliser une autre version PHP que celle retournée par php -v.

Listez les services PHP-FPM actifs :

systemctl list-units 'php*-fpm.service' --state=runningLangage du code : PHP (php)

Vérifiez aussi la version PHP utilisée par le vhost Nginx ou Apache, selon votre configuration.

Redémarrer PHP-FPM ou Apache

Après installation ou réinstallation de l’extension MySQL, redémarrez le service PHP concerné.

Avec PHP-FPM :

sudo systemctl restart php8.4-fpmLangage du code : CSS (css)

ou :

sudo systemctl restart php8.5-fpmLangage du code : CSS (css)

Avec Apache et mod_php :

sudo systemctl restart apache2

Vous n’avez normalement pas besoin de redémarrer MySQL pour charger une extension PHP. Le problème se situe côté PHP, pas côté serveur MySQL. En revanche, si vous venez aussi de mettre à jour MySQL ou MariaDB, un redémarrage contrôlé du service MySQL peut faire partie de votre maintenance.

Réinstaller proprement les extensions PHP MySQL

Si l’environnement a été mélangé après plusieurs dépôts, upgrades ou versions PHP, réinstallez l’extension proprement.

Exemple avec PHP 8.4 :

sudo apt update
sudo apt install --reinstall php8.4-mysql
sudo systemctl restart php8.4-fpmLangage du code : CSS (css)

Pour Apache :

sudo apt install --reinstall php8.4-mysql
sudo systemctl restart apache2Langage du code : CSS (css)

Vérifiez ensuite :

php8.4 -m | grep -Ei 'mysql|mysqli|pdo'
php8.4 -i | grep -Ei 'mysqlnd|Client API'Langage du code : JavaScript (javascript)

Cas WordPress : ne modifiez pas WordPress pour ce problème

WordPress n’utilise plus mysql_connect() sur les versions modernes. Il utilise l’extension disponible côté PHP, généralement mysqli avec mysqlnd.

Si un site WordPress récent affiche une erreur de connexion MySQL après une mise à jour serveur, vérifiez plutôt :

• la version PHP réellement utilisée par le vhost ;
• la présence de mysqli et pdo_mysql ;
• la présence de mysqlnd ;
• les extensions chargées dans PHP-FPM, pas seulement en CLI ;
• les identifiants dans wp-config.php ;
• la disponibilité du serveur MySQL ;
• les sockets Unix si MySQL écoute localement.

Commande utile depuis la racine du site :

wp --info
wp db check

Si wp db check fonctionne en CLI mais que le site échoue dans le navigateur, vous avez probablement une différence entre PHP CLI et PHP-FPM. Classique. Agaçant. Mais classique.

Vérifier les bibliothèques MySQL chargées par PHP

Sur un système ancien ou très custom, vous pouvez vérifier les bibliothèques liées à l’extension PHP MySQL.

Trouvez d’abord le chemin de l’extension mysqli :

php -i | grep extension_dir

Puis inspectez les dépendances dynamiques du module, en adaptant le chemin :

ldd /usr/lib/php/20230831/mysqli.so

Sur une configuration moderne avec mysqlnd, vous ne devriez normalement pas voir une dépendance directe problématique vers une vieille libmysqlclient.

Si vous voyez plusieurs bibliothèques MySQL concurrentes provenant de dépôts différents, nettoyez les paquets incohérents. Les mélanges de dépôts MySQL, MariaDB, Ondřej PHP, paquets compilés à la main et vieux modules PHP sont souvent la vraie source du désordre.

Checklist rapide de correction

Voici la séquence que j’utiliserais sur un serveur Ubuntu ou Debian moderne :

# 1. Vérifier la version PHP CLI.
php -v

# 2. Vérifier les extensions MySQL chargées.
php -m | grep -Ei 'mysql|mysqli|pdo'

# 3. Vérifier mysqlnd.
php -i | grep -Ei 'mysqlnd|Client API'

# 4. Installer ou réinstaller l’extension MySQL pour PHP.
sudo apt update
sudo apt install --reinstall php-mysql

# Ou pour une version précise :
sudo apt install --reinstall php8.4-mysql

# 5. Redémarrer PHP-FPM si utilisé.
sudo systemctl restart php8.4-fpm

# 6. Redémarrer Apache si mod_php est utilisé.
sudo systemctl restart apache2

# 7. Vérifier les services FPM actifs.
systemctl list-units 'php*-fpm.service' --state=runningLangage du code : PHP (php)

Et si l’application utilise encore mysql_connect(), la vraie correction est une migration de code vers mysqli ou PDO_MySQL.

Conclusion

L’erreur Headers and client library minor version mismatch venait historiquement d’un décalage entre les headers MySQL utilisés à la compilation et la bibliothèque cliente chargée par PHP.

Mais en 2026, si le message mentionne mysql_connect(), l’application est surtout trop ancienne. Cette fonction appartient à l’ancienne extension mysql, dépréciée en PHP 5.5 et supprimée en PHP 7.0. Il faut migrer vers mysqli ou PDO_MySQL.

Côté serveur, installez l’extension MySQL moderne de PHP :

sudo apt install php-mysql

ou pour une version précise :

sudo apt install php8.4-mysqlLangage du code : CSS (css)

Puis vérifiez que mysqlnd, mysqli et pdo_mysql sont bien chargés :

php -m | grep -Ei 'mysql|mysqli|pdo'
php -i | grep -Ei 'mysqlnd|Client API'Langage du code : JavaScript (javascript)

Le bon résumé : ne cherchez pas à ressusciter mysql_connect(). Remplacez-le.

Sources

• PHP Manual : mysql_connect
• PHP Manual : MySQL Native Driver overview
• PHP Manual : mysqlnd
• PHP Manual : installation de mysqli
• PHP Manual : mysqli overview

Report a typo