Dépannage

Le message « Unable to establish a connection to the database » signifie qu’oxmysql n’a pas pu ouvrir de connexion vers MariaDB ou MySQL : il réessaie toutes les 30 secondes, et les ressources qui attendent la base restent bloquées. La ligne suivante donne la cause : ECONNREFUSED (la base ne tourne pas ou n’écoute pas sur ce port), Access denied (utilisateur ou mot de passe refusé), Unknown database (base inexistante). Le coupable le plus fréquent est la ligne set mysql_connection_string du server.cfg.

Mise à jour : 15 novembre 2026

Ce qu’affiche oxmysql

Quand la connexion échoue, oxmysql écrit trois lignes au démarrage. La première est générique, la deuxième contient la vraie cause :

Unable to establish a connection to the database (ER_ACCESS_DENIED_ERROR)!
Error 1045: Access denied for user 'fivem'@'localhost' (using password: YES)
See https://github.com/overextended/oxmysql/issues/154 for more information.

Juste après, oxmysql affiche la configuration qu’il a tirée de votre chaîne : hôte, port, utilisateur, base, avec le mot de passe remplacé par des étoiles. Comparez-la avec ce que vous pensiez avoir écrit. Un utilisateur ou un hôte inattendu s’y repère en une seconde.

Tant que la connexion échoue, oxmysql retente toutes les 30 secondes, et les requêtes des autres ressources attendent au lieu d’échouer. Le serveur paraît démarré, mais les personnages ne chargent jamais. Quand tout va bien, la console affiche la version de la base entre crochets, suivie de Database server connection established!.

Les causes, classées par code d’erreur

Le code entre parenthèses et le texte de la deuxième ligne vous orientent tout de suite. Du plus fréquent au plus rare :

ECONNREFUSED
Rien n’écoute à l’adresse et au port indiqués. MariaDB ou MySQL est arrêté, ou écoute sur un autre port que 3306, ce qui arrive souvent quand deux installations cohabitent. Si l’adresse affichée est ::1:3306, localhost a été traduit en adresse IPv6 alors que la base n’écoute qu’en IPv4 : écrivez 127.0.0.1 à la place.
Access denied for user
Erreur 1045 : la base refuse l’utilisateur ou le mot de passe. Lisez la fin du message. using password: NO signifie qu’aucun mot de passe n’est parti : il manque dans la chaîne, ou la convar n’a pas été lue du tout, auquel cas oxmysql se rabat sur mysql://root@localhost, d’où un root que vous n’avez jamais écrit. L’hôte entre apostrophes est celui que la base a vu : l’utilisateur doit exister pour cet hôte-là.
Unknown database
Erreur 1049 : la base nommée n’existe pas. Elle n’a pas été créée, son nom contient une faute, ou la casse diffère : sous Linux, MaVille et maville sont deux bases distinctes.
ENOTFOUND, ETIMEDOUT
getaddrinfo ENOTFOUND : le nom d’hôte n’existe pas, souvent parce qu’un caractère spécial du mot de passe a coupé la chaîne (voir plus bas). ETIMEDOUT : la base est sur une autre machine et un pare-feu bloque le port ; oxmysql patiente 60 secondes avant d’abandonner.
Host … is not allowed
Erreur 1130, dont le message contient is not allowed to connect to this. La base tourne sur une autre machine, et l’utilisateur n’existe que pour localhost.
auth_gssapi_client
oxmysql affiche Requested authentication using unknown plugin auth_gssapi_client. Le compte utilisé, souvent root, réclame une méthode d’authentification que le pilote d’oxmysql ne gère pas. Créez un utilisateur dédié avec mot de passe. Les signalements citent aussi des MariaDB anciennes, livrées dans des paquets tout-en-un : installez une version récente.

Écrire une mysql_connection_string valide

oxmysql lit la convar mysql_connection_string, sous l’une des deux formes que donne sa documentation :

# Forme URL
set mysql_connection_string "mysql://fivem:[email protected]:3306/maville?charset=utf8mb4"

# Forme clé=valeur
set mysql_connection_string "user=fivem;password=MotDePasseLong24;host=127.0.0.1;port=3306;database=maville"
  • Toujours set, jamais setr ni sets : setr enverrait la chaîne à chaque joueur, sets la publierait dans la liste des serveurs.
  • La ligne avant ensure oxmysql. oxmysql lit la convar une seule fois, à son démarrage.
  • Pas d’encodage URL. oxmysql ne décode pas les %40 et autres %xx : ils partent tels quels, et la base répond Access denied.
  • Pas de caractères spéciaux dans la forme URL. Un : coupe le mot de passe. Un / ou un ? décale toute la chaîne, et oxmysql cherche un hôte qui porte le nom de l’utilisateur. Un # la rend invalide : mysql_connection_string structure was invalid. La documentation déconseille ; , / ? : @ & = + $ # : prenez un mot de passe long, en lettres et chiffres. À défaut, la forme clé=valeur supporte une partie de ces caractères, mais ni ; ni =.
  • Un server.cfg enregistré en UTF-8, et aucun accent dans le mot de passe : un fichier réenregistré dans un autre encodage change leurs octets.

Un piège avec txAdmin : son assistant d’installation teste la connexion avec le mot de passe brut, puis l’écrit tel quel dans l’URL. Un mot de passe qui contient : ou / réussit le test et casse oxmysql au premier démarrage. Pour repartir d’une configuration propre, le générateur de server.cfg écrit la ligne pour vous.

Corriger pas à pas

1. La base tourne
Sous Windows, ouvrez l’application Services et vérifiez que le service MariaDB ou MySQL est démarré. Sous Linux : systemctl status mariadb.
2. Le bon port
Sous Windows : netstat -ano | findstr 3306. Sous Linux : ss -ltnp | grep 3306. Aucune ligne : la base écoute ailleurs. Cherchez le port dans sa configuration et reportez-le dans la chaîne.
3. Les identifiants
Testez-les hors de FiveM : mysql -h 127.0.0.1 -P 3306 -u fivem -p maville, ou mariadb avec les mêmes options. Si la connexion échoue ici aussi, le problème vient de la base, pas de FiveM.
4. Base et utilisateur
S’ils manquent, créez-les depuis un compte administrateur avec les commandes ci-dessous.
5. La chaîne
Corrigez-la, enregistrez le fichier, puis redémarrez le serveur entier.
CREATE DATABASE maville CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'fivem'@'localhost' IDENTIFIED BY 'MotDePasseLong24';
GRANT ALL PRIVILEGES ON maville.* TO 'fivem'@'localhost';

Redémarrez tout le serveur plutôt qu’oxmysql seul. Arrêter oxmysql arrête aussi les ressources qui le déclarent comme dépendance, et un restart ne les relance pas.

Vérifier que la connexion tient

  • La console affiche Database server connection established! une fois, sans Unable to establish derrière.
  • Un personnage créé, une déconnexion, une reconnexion : il est toujours là.
  • La nouvelle ligne apparaît dans la table des joueurs de votre framework.

Ce qu’on a vu en production sur un grand serveur RP français : un serveur de test branché sur une copie incomplète de la base. La connexion passait, mais la table du catalogue d’objets était vide, et l’inventaire refusait de démarrer. Une connexion établie ne prouve pas que c’est la bonne base : comparez la copie à l’originale, table par table.

Éviter que ça revienne

  • Un utilisateur réservé au serveur, jamais root, avec des droits sur sa seule base.
  • Le service de la base en démarrage automatique : type « Automatique » dans Services sous Windows, systemctl enable mariadb sous Linux. Après un redémarrage de la machine, la base repart seule.
  • Le port 3306 fermé à Internet, comme l’explique notre guide pour protéger un serveur FiveM.
  • Une base séparée pour le serveur de test, avec son propre utilisateur.
  • La chaîne dans un fichier à part, chargé par exec, hors de tout dépôt git.

Autre cas vécu : des scripts qui interrogeaient la base ou le framework dès leur chargement, avant que tout soit prêt. L’erreur levée à ce moment arrêtait le reste du fichier, et la fonction manquait en jeu sans autre message. Une fois la connexion réparée, relisez donc aussi les erreurs des autres ressources.

Sur GeoBase, la base de données est installée et reliée au serveur avec l’hébergement : il n’y a pas de chaîne de connexion à écrire.

Questions fréquentes

Où mettre mysql_connection_string ?
Dans le server.cfg, ou dans un fichier chargé par exec, avec set, avant la ligne ensure oxmysql.
Faut-il encoder les caractères spéciaux du mot de passe ?
Non. oxmysql ne décode pas l’encodage URL : un %40 part tel quel, et la base le refuse. Passez à un mot de passe en lettres et chiffres, ou à la forme clé=valeur.
oxmysql fonctionne-t-il avec MySQL ?
Oui, avec MySQL comme avec MariaDB. Sa documentation recommande MariaDB.
Pourquoi le serveur démarre mais les personnages ne chargent pas ?
Si oxmysql n’est pas connecté, il retente toutes les 30 secondes et les requêtes restent en attente : l’écran de chargement ne finit jamais. Cherchez Unable to establish a connection dans la console.

À lire ensuite