QBCore Frameworkqbcore.netCommunity docs
On this page

6 min read

QBCore oxmysql Errors

Separate three failure layers: the resource did not load, the database connection failed, or a connected query failed. A SQL unknown column error is not repaired by changing the resource start order. A missing compiled resource is not repaired by importing a player table.

This guide references the oxmysql Lua bridge at 030d3bda, QBCore SQL at 9b3cddcc and the linked installation documentation checked on 21 September 2026. Check your installed release before applying version-specific changes. The tests below are manual staging checks, not claimed execution on a live FiveM server.

Evidence to collect

Record the first startup error, resource folder and manifest, installed oxmysql release/commit, database engine/version, active txAdmin data directory, and the failing query's resource/file/line. Record the database hostname and database name privately; redact the password and any player data before sharing logs.

Message or observationLayerInspect next
Couldn't find resource oxmysqlPackage/pathExact folder name, nesting and actual manifest
Missing server script or module at startupPackage/buildRelease asset versus unbuilt source archive
MySQL is nil in a custom scriptCaller initializationServer-side library import before the caller
ECONNREFUSEDConnectionDatabase listener, host/port and container network
Access denied for userAuthenticationCredentials and the database account's allowed host
Unknown databaseDatabase selectionDatabase name in the active connection string
Table ... doesn't existSchema or wrong selected databaseOwning resource's exact SQL and SELECT DATABASE()
Unknown column ...Schema/versionActual columns versus target code and migration history
Slow-query warningPerformanceQuery duration/frequency and server stalls, not only hardware

Safe diagnostic

Install the release package, not an unbuilt source snapshot

Use the release asset specified by the oxmysql installation documentation. GitHub's automatically generated Source code archives contain development source and are not interchangeable with a packaged resource. An operator building from source must follow that repository's build process and confirm every script declared by the resulting manifest exists.

The active data directory should contain an oxmysql resource whose manifest is directly inside that folder, not oxmysql-main/oxmysql/. Do not fabricate a manifest to disguise an incomplete download. Keep the original archive and checksum alongside your deployment record.

A Cfx.re report from 29 October 2024 illustrates this distinction: changing startup order did not solve the issue, while switching from the source download to the packaged oxmysql.zip did. That report supports checking the package; it is not evidence that every database failure has that cause.

Verify configuration and startup order

Set the connection string before starting oxmysql in the configuration used by the running profile. The following is a template with placeholder credentials, not a working account:

# Server-only: never use setr or sets for database credentials.
set mysql_connection_string "mysql://qb_app:[email protected]:3306/qb_staging?charset=utf8mb4"
ensure oxmysql
ensure qb-core

Use a dedicated account and the actual database name. Encode reserved characters correctly when using a URI; the official documentation also describes a key/value connection-string form. Do not solve encoding problems by weakening the password. Keep credentials out of Git, client files and public screenshots.

127.0.0.1 means the environment running FXServer. Inside a container it normally refers to that container, not the database container or host. Use the database address provided by your deployment/network configuration. Do not expose MySQL publicly or open broad firewall rules just to make a test pass.

Do not duplicate an existing recipe's startup lines without reviewing them. Check included configuration files for another connection-string assignment or a conflicting database resource.

Verify a read-only query

Create a temporary staging-only resource resources/[custom]/docs_dbcheck/ with these files. It has no network event and modifies no database data.

fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'
server_only 'yes'

dependency 'oxmysql'
server_scripts {
    '@oxmysql/lib/MySQL.lua',
    'server.lua'
}

server.lua:

MySQL.ready(function()
    local ok, row = pcall(function()
        return MySQL.single.await('SELECT 1 AS ok, DATABASE() AS db')
    end)

    if not ok or not row then
        print('[docs_dbcheck] query failed; inspect the first oxmysql error privately')
        return
    end

    print(('[docs_dbcheck] ok=%s database=%s'):format(tostring(row.ok), tostring(row.db)))
end)

Start docs_dbcheck after oxmysql. Expected result in the server console: ok=1 and the intended database name. If no ready callback runs, first inspect oxmysql's startup/connection errors. A passing SELECT 1 proves a basic connection and selected database, not that all resource tables, account privileges or production queries are correct.

Remove the diagnostic resource from the startup configuration after testing. For parameterized player reads, see database examples.

Fix

Connection errors

For a refused connection, confirm the database service is running and reachable from the FXServer host or container at the configured port. Compare with a database-client connection from the same environment using the same non-root account. A successful connection from your laptop does not prove server-to-database connectivity.

For access denied, check the account, password and host restrictions with the database administrator. Do not grant privileges to every host as a generic workaround. For unknown database, check spelling and whether you edited the live profile rather than a dormant server.cfg.

For a nil MySQL global, ensure @oxmysql/lib/MySQL.lua precedes your server code in server_scripts. Do not load that library through shared_scripts or expose database queries directly to the browser/client.

Schema errors are not connection errors

Run read-only inspection in the selected staging database:

SELECT DATABASE();
SHOW TABLES LIKE 'players';
SHOW TABLES LIKE 'player_vehicles';

Only if the relevant table exists, inspect its real definition:

SHOW CREATE TABLE players;
SHOW COLUMNS FROM players;

Identify the resource owning the failed query. For the sources linked below, core tables come from qb-core/qbcore.sql, vehicle ownership from qb-vehicleshop/vehshop.sql, and identifier-based inventory storage from qb-inventory/qb-inventory.sql. The database ownership table keeps these roles separate.

Compare those files at the deployed and target commits, along with any migration script. CREATE TABLE IF NOT EXISTS does not add missing columns to an existing table. Do not guess a column's type from its name, repeatedly import an entire SQL folder or replace the player schema with an unrelated template. Apply the reviewed migration once to a restored staging database and verify the actual resource workflow.

Slow queries and temporary debugging

Reproduce one measured operation. Record its query shape, timing and frequency, and inspect existing indexes before adding new ones. Check for a server hitch at the same time. Debug output can contain query parameters and player data: enable it only for a bounded diagnostic session, retain logs privately and turn it off afterward. See server optimization.

Manual acceptance checks

Confirm a clean startup, the read-only connection test, one existing character login, one new character flow and the specific resource operation that previously failed. For inventory migrations, additionally check stash/trunk/glovebox contents before and after reconnect. Verify that credentials are not present in replicated convars, browser downloads or committed files.

Rollback

For a connection/configuration-only change, restore the prior verified configuration and resource version; do not overwrite player records unnecessarily. If a schema or data migration was applied, restore the matching code/database snapshot or use a separately reviewed reverse migration. Preserve legitimate writes after the backup through a planned reconciliation process. Use the resource-update workflow rather than trial-and-error imports on production.

Sources

Found an issue in this guide?

Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.

On this page