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 observation | Layer | Inspect next |
|---|---|---|
Couldn't find resource oxmysql | Package/path | Exact folder name, nesting and actual manifest |
| Missing server script or module at startup | Package/build | Release asset versus unbuilt source archive |
MySQL is nil in a custom script | Caller initialization | Server-side library import before the caller |
ECONNREFUSED | Connection | Database listener, host/port and container network |
Access denied for user | Authentication | Credentials and the database account's allowed host |
Unknown database | Database selection | Database name in the active connection string |
Table ... doesn't exist | Schema or wrong selected database | Owning resource's exact SQL and SELECT DATABASE() |
Unknown column ... | Schema/version | Actual columns versus target code and migration history |
| Slow-query warning | Performance | Query 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-coreUse 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
- OxMySQL installation and configuration, checked 2026-09-21.
- Lua bridge and query methods, 030d3bda and connection parsing.
- Core SQL, 9b3cddcc, vehicle SQL, e8652970 and inventory SQL, dc3d07fc.
- Cfx.re package-selection support case, 2024-10-29.
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.