# Troubleshooting ESX Legacy (/docs/getting-started/troubleshooting)

This page lists the errors ESX Legacy server owners and developers run into most often, what causes them and how to fix them. Search the page (Ctrl+F) for the exact text of your error.

## How to find the real error [#how-to-find-the-real-error]

Before you change anything, find the **first** error:

1. **Server console** or txAdmin **Live Console**: server-side errors, resource start failures, database errors.
2. **F8 console** in game: client-side script errors.
3. Scroll up to the first red line after the server started. One root cause (for example the database being down) produces dozens of follow-up errors in other resources.

A Lua error tells you the resource, file and line: `@my_script/server/main.lua:12: attempt to index a nil value`. Open that file at that line.

## "attempt to index a nil value (global 'ESX')" [#attempt-to-index-a-nil-value-global-esx]

Also seen as `ESX is nil` or `attempt to index a nil value (field 'PlayerData')`.

The resource uses `ESX` but never received the shared object. Causes, from most to least common:

1. **Missing import.** Add it to the resource's `fxmanifest.lua`, above your own files:
   ```lua title="fxmanifest.lua"
   shared_scripts {
       '@es_extended/imports.lua',
       'config.lua',
   }
   ```
2. **Wrong start order.** The resource starts before `es_extended`. Move its `ensure` line below the ESX lines in `server.cfg` and add `dependency 'es_extended'` to its manifest.
3. **Old ESX script.** It uses `TriggerEvent('esx:getSharedObject', function(obj) ESX = obj end)` inside a thread with a wait loop. Replace that block with the import above. See [Convert old ESX scripts](/docs/guides/convert-old-esx-scripts).
4. **es_extended is not running at all.** Check the console for why it failed to start (see below).

## "No such export getSharedObject in resource es_extended" [#no-such-export-getsharedobject-in-resource-es_extended]

Same root cause as above: `es_extended` is not started yet, failed to start, or the folder is not called exactly `es_extended`. Fix the start order or the start failure first.

## "Couldn't load resource es_extended" / es_extended does not start [#couldnt-load-resource-es_extended--es_extended-does-not-start]

`es_extended` declares `esx_lib` and `oxmysql` as dependencies. If FiveM cannot find one, it refuses to start `es_extended`, and every ESX resource fails after it. Check:

- `resources/[core]/esx_lib` exists. It is new in recent releases; servers updated by copying only `es_extended` often miss it.
- `oxmysql` exists and comes from the **release zip**, not the GitHub source code.
- There is exactly one `es_extended` folder and its `fxmanifest.lua` sits directly inside it (not `es_extended/es_extended/fxmanifest.lua` or `es_extended-main`).
- Your server build is current. Old builds miss natives that `es_extended` requires.

## oxmysql cannot connect to the database [#oxmysql-cannot-connect-to-the-database]

Players get kicked with `[ESX] OxMySQL Was Unable To Connect to your database`. The server console shows the actual database error from oxmysql at startup. Typical messages:

| Error | Meaning | Fix |
| --- | --- | --- |
| `ECONNREFUSED` | Nothing listens on that host and port. | Start MariaDB (Windows: Services, `MariaDB`). Check host and port `3306`. |
| `ER_ACCESS_DENIED_ERROR` | Wrong user or password. | Test the same credentials in HeidiSQL. Check for special characters in the password (URL-encode them). |
| `ER_BAD_DB_ERROR` / `Unknown database` | The database name does not exist. | Create it, or fix the name in the connection string. |
| `ER_NO_SUCH_TABLE` / `Table '...users' doesn't exist` | Connected, but `legacy.sql` was never imported into this database. | Import `[SQL]/legacy.sql` into the database named in the string. |

The connection string formats are explained in [server.cfg](/docs/getting-started/server-cfg#database-connection).

## "ESX Requires Onesync Infinity to work" [#esx-requires-onesync-infinity-to-work]

The server runs with OneSync `off` or `legacy`. Set `set onesync on` in `server.cfg`. On txAdmin, check **Settings > FXServer**: txAdmin's OneSync setting overrides the config file.

## "ESX Requires a minimum Artifact version of 10188" [#esx-requires-a-minimum-artifact-version-of-10188]

Your FiveM server build is too old. Download a current build and replace the server binaries (not your data folder).

## "Native 0x... is not supported" or crashes after a build update [#native-0x-is-not-supported-or-crashes-after-a-build-update]

The server build has a known problem. Switch to the latest build, or to a known-good one listed on [artifacts.jgscripts.com](https://artifacts.jgscripts.com), which marks broken builds.

## Players are stuck on the loading screen [#players-are-stuck-on-the-loading-screen]

The loading screen stays until the character loads. If it never disappears:

1. **Check F8 and the server console** while the player is stuck. A script error during load (often in a HUD or a custom spawn script) stops the chain.
2. **Database errors.** If the `users` query fails, the player never loads. See the oxmysql section above.
3. **Missing [core] resources.** Without `esx_multicharacter` or `esx_identity`, character creation cannot finish. Check that `ensure [core]` is in `server.cfg` and all core resources started.
4. **Conflicting spawn or loading screen resources.** Two resources that both try to spawn the player or shut down the loading screen block each other. Remove duplicates (for example a second loading screen or spawn manager from another framework).
5. **Game build mismatch.** A resource that streams assets for a newer game build than `sv_enforceGameBuild` can hang the client while loading.

## Multicharacter problems [#multicharacter-problems]

### "Unable to start Multicharacter - unable to determine database from mysql_connection_string" [#unable-to-start-multicharacter---unable-to-determine-database-from-mysql_connection_string]

`esx_multicharacter` reads the database name from `mysql_connection_string`. The convar is empty or in an unexpected format. Use one of the two formats from [server.cfg](/docs/getting-started/server-cfg#database-connection) and make sure the database name is included.

### Old characters disappear after installing multicharacter [#old-characters-disappear-after-installing-multicharacter]

With multicharacter, identifiers in `users` get a prefix per slot (by default `char1:`, `char2:` and so on, set by `Config.Prefix`). Characters created before multicharacter was installed do not have the prefix, so they are not listed. Back up the database, then update the old rows, for example:

```sql
UPDATE `users` SET `identifier` = CONCAT('char1:', `identifier`) WHERE `identifier` NOT LIKE 'char%:%';
```

Other tables that store identifiers (such as `owned_vehicles.owner`) need the same change.

### "Error code: identifier-active" or "There is already an active session for this character" [#error-code-identifier-active-or-there-is-already-an-active-session-for-this-character]

Another session with the same identifier is still registered, usually after a crash or a quick reconnect, or two people share an account. Wait for the old session to time out or restart the server. If it happens often, check for scripts that error in `playerDropped` and prevent cleanup.

## Admin commands say "access denied" [#admin-commands-say-access-denied]

- Your license is not in `group.admin`, or your character was created before you added it. See [Admin permissions](/docs/guides/admin-permissions).
- The four `add_ace resource.es_extended ...` lines are missing from `server.cfg`, so ESX cannot grant permissions.
- You are typing an ox_inventory command name on a server with the default inventory or vice versa: `/giveitem` and `/giveweapon` from ESX only exist without ox_inventory.

## "Item "xyz" was used but does not exist!" [#item-xyz-was-used-but-does-not-exist]

A script tries to give, remove or check an item that is not in the `items` table. Add the item (see [Add items](/docs/guides/add-items)), then run `/refreshitems` or restart. If you use ox_inventory, items are defined in its data files instead.

## "Server restart required!" repeats [#server-restart-required-repeats]

ESX ran database migrations and needs one restart. Restart the server. If it shows again on every start, a migration fails before it is recorded: scroll up for `Failed migration` and fix that error. See [Updating](/docs/getting-started/updating#how-esx-migrations-work).

## Still stuck? [#still-stuck]

- Search the [esx_core issues](https://github.com/esx-framework/esx_core/issues) for your exact error message.
- Ask in the official [ESX Discord](https://discord.esx-framework.org/). Include the full error, your ESX version, server build number and what you changed last.
- Never share your license key, database password or bot tokens when asking for help.

## Related [#related]

- [server.cfg for ESX](/docs/getting-started/server-cfg)
- [Updating ESX Legacy](/docs/getting-started/updating)
- [esx_multicharacter](/docs/core/esx_multicharacter)
- [FAQ](/docs/faq)