oxmysql "Unable to establish a connection to the database" Fix

The oxmysql error "Unable to establish a connection to the database" means your FiveM server could not log in to MySQL or MariaDB with the details in mysql_connection_string. The code in brackets tells you why: ECONNREFUSED means nothing answered at that address, ER_ACCESS_DENIED_ERROR means a wrong user or password, and ER_BAD_DB_ERROR means the database name does not exist.

What the error looks like

oxmysql prints the error when it starts, followed by the settings it tried. In your server console or txAdmin Live Console, after the script:oxmysql prefix, it looks like this:

Unable to establish a connection to the database (ECONNREFUSED)!
Error: connect ECONNREFUSED 127.0.0.1:3306
See https://github.com/overextended/oxmysql/issues/154 for more information.

Right after it, the scripts that need the database fail too. QBCore, Qbox and ESX will not load characters, and players get stuck on the loading screen or are dropped. Fix the connection and those errors go away with it.

Which oxmysql error code do I have?

Read the code in brackets on the first line and jump to its fix.

Is mysql_connection_string set at all?

Check this first. oxmysql reads one convar, mysql_connection_string. If it is missing, empty or set after oxmysql starts, oxmysql falls back to mysql://root@localhost, which gives the classic ECONNREFUSED 127.0.0.1:3306 or Access denied for user 'root'@'localhost' (using password: NO).

Open server.cfg (in txAdmin: CFG Editor) and make sure the line exists, uses set, and comes before ensure oxmysql:

set mysql_connection_string "mysql://USER:PASSWORD@HOST:3306/DATABASE?charset=utf8mb4"

ensure oxmysql
ensure ox_lib
ensure qbx_core

oxmysql accepts two formats. Use one, not both mixed:

The semicolon format also accepts the older names server=, uid= and pwd=.

Fix ECONNREFUSED

ECONNREFUSED means the server reached the address and nothing accepted the connection.

1. Is the database running? On your own PC or VPS, start MariaDB or MySQL. On Windows check Services for MariaDB or MySQL. On Linux run sudo systemctl status mariadb.
2. Is the host right? localhost and 127.0.0.1 only work when the database runs on the same machine as FXServer. With hosted servers and Docker based panels the database is usually somewhere else, so use the host your provider gives you.
3. Is the port right? MySQL and MariaDB use 3306 by default. If yours runs on another port, put it in the string.
4. Is it listening on the right address? A database bound only to 127.0.0.1 refuses connections from another machine. Set bind-address in the MariaDB config to the address you need, and never expose it to the whole internet without a firewall.

Fix ER_ACCESS_DENIED_ERROR (Error 1045)

The database answered but refused the login.

• Check the password. Copy it again rather than retyping it.
• Encode special characters in URI format. Characters like @, :, /, #, ? and % break a mysql:// string. Either URL encode them (@ becomes %40, # becomes %23) or switch to the semicolon format, or pick a password without them.
• "using password: NO" means no password was sent at all. The convar is missing or the password part is empty.
• Check where the user may connect from. A user created as 'fivem'@'localhost' cannot log in from another machine. Create it for the right host:

CREATE USER 'fivem'@'%' IDENTIFIED BY 'S3cret';
GRANT ALL PRIVILEGES ON qbcore.* TO 'fivem'@'%';
FLUSH PRIVILEGES;

Use a specific IP instead of % if you can.

Fix ER_BAD_DB_ERROR (Error 1049)

The login worked but the database name does not exist. Database names are case sensitive on Linux, so QBCore and qbcore are different. Create it, or correct the name in the string:

CREATE DATABASE qbcore CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

An empty database also needs its tables. If the connection works but you then see Table 'qbcore.players' doesn't exist or Table 'es_extended.users' doesn't exist, import the framework's .sql file with HeidiSQL or the mysql command line, or redeploy with a txAdmin recipe, which runs the SQL for you.

Fix ETIMEDOUT and ENOTFOUND

• ETIMEDOUT: the packets never got an answer. A firewall on the database machine or your provider is dropping port 3306. Allow it from your FiveM server's IP only.
• ENOTFOUND: the hostname has a typo, or a DNS name that has not been created yet. Try the database IP directly to confirm.

"No such export" errors after the database works

If oxmysql now connects but you see No such export execute in resource oxmysql or similar, a resource started before oxmysql. Move ensure oxmysql above every resource that uses it in server.cfg, usually the very first ensure after the default resources. Then restart the whole server rather than one resource.

On a GamezServers FiveM server

Every FiveM server with us comes with its own MySQL database. When you deploy a QBCore, Qbox or ESX recipe in txAdmin, the host, port, user, password and database name are filled in for you, so the connection string is right from the start. If you edited it by hand, the correct details are under Settings in your panel, and you can paste them into txAdmin's CFG Editor or use them in HeidiSQL. Take a one click backup before importing SQL files.

For other early setup problems, see the FiveM license key error and FiveM server not showing in the server list guides, or start over with how to host a FiveM server.

FAQ

Where do I put mysql_connection_string?

In server.cfg, as set mysql_connection_string "...", above the line ensure oxmysql. In txAdmin, edit it in the CFG Editor and restart the server.

Why does oxmysql try to connect to root@localhost?

That is its default when mysql_connection_string is missing or empty. Add the convar with your real database details.

Can I use 127.0.0.1 as the database host?

Only if MySQL or MariaDB runs on the same machine as the FiveM server. Hosted servers usually have the database on another address, which your provider shows you.

Does oxmysql work with MariaDB?

Yes. oxmysql works with both MySQL and MariaDB, and MariaDB is the common choice for self hosted FiveM servers.

My password has an @ in it. Is that the problem?

Very likely, if you use the mysql:// format. URL encode it as %40 or switch to the user=...;password=... format.