# 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:

```cfg
# Server-only: never use setr or sets for database credentials.
set mysql_connection_string "mysql://qb_app:REPLACE_WITH_URL_ENCODED_PASSWORD@127.0.0.1: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`:

```lua
fx_version 'cerulean'
game 'gta5'
server_only 'yes'

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

`server.lua`:

```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](/docs/database#essential-queries).

## 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:

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

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

```sql
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](/docs/database#resource-specific-tables) 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](/docs/performance/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](/docs/migration/resource-updates) rather than trial-and-error imports on production.

## Sources

- [OxMySQL installation and configuration](https://overextended.dev/docs/oxmysql), checked 2026-09-21.
- [Lua bridge and query methods, 030d3bda](https://github.com/overextended/oxmysql/blob/030d3bda11098fc4a78f1940545b674c374daa45/lib/MySQL.lua) and [connection parsing](https://github.com/overextended/oxmysql/blob/030d3bda11098fc4a78f1940545b674c374daa45/src/config.ts).
- [Core SQL, 9b3cddcc](https://github.com/qbcore-fivem/qb-core/blob/9b3cddcce93e5e12cbcf6b47b866b687d32ac7bf/qbcore.sql), [vehicle SQL, e8652970](https://github.com/qbcore-fivem/qb-vehicleshop/blob/e8652970aca3324d2a18a440f3d3871715338da8/vehshop.sql) and [inventory SQL, dc3d07fc](https://github.com/qbcore-fivem/qb-inventory/blob/dc3d07fc60139de569df38c5ac178ed4cada4577/qb-inventory.sql).
- [Cfx.re package-selection support case](https://forum.cfx.re/t/qbcore-is-not-working/5278585), 2024-10-29.
