Troubleshooting

Common issues

Scuba tank or refill does nothing when used

Almost always the client.event hooks were dropped during the merge.

• scuba_tank must keep its hook to diving:client:toggleTank.
• tank_refill must keep its hook to diving:client:useRefill.

Reopen the shipped medit8z_diving/items.lua, copy the client = { ... } blocks back onto the merged entries in ox_inventory/data/items.lua, and restart ox_inventory.

Boat won't spawn or no keys issued

The boat rental relies on qbx_vehiclekeys. Confirm:

• qbx_vehiclekeys is started before medit8z_diving (Qbox default load order is fine).
• The boat spawn point in Config.Boat.spawnPoint is actually in water on your map. The default is Vespucci Beach pier — re-scout for custom maps.
• The player has enough money for Config.Boat.price. The boatNoMoney toast confirms this.

If the boat spawns but keys don't transfer, the install is missing qbx_vehiclekeys entirely — diving is the only Medit8z script that requires it.

No crates in a zone

Three causes, in order of frequency:

1. The respawn timer hasn't elapsed yet. Once a zone has been swept (someone searched a crate in it), it's empty until Config.Crates.respawnTimer (default 1 hour) finishes.
2. The first crate in the zone hasn't been searched yet — that's actually fine, the crates are there, you just need to swim closer. Crate props stream in only at moderate range.
3. You're playing on a custom map and the shipped spawnPoints no longer fall on the ocean floor. Use the debug commands below to re-record points.

You can force-respawn a zone with /divingspawn [zone] while debug mode is on.

Database errors on first start

If the server log shows install.sql not found - skipping schema setup, the resource folder is incomplete — re-upload it. If the log shows MySQL errors instead, confirm oxmysql is running and the connection string is valid before medit8z_diving starts.

To do a clean reset of boat persistence:

DROP TABLE diving_boats;

The table will be recreated on the next start.

Scuba clothing looks wrong

The defaults set ped component 8 (undershirt) to drawable 151 (male) / 187 (female), which targets vanilla GTA V peds. If you run a custom clothing system (illenium-appearance, fivem-appearance, qb-clothing) the slot/asset map will be different and you'll see either a clipping outfit or no scuba harness at all.

Edit Config.Tank.clothing to point at the slot and drawable that shows the harness on your peds:

Config.Tank.clothing = {
    component = 8,                                   -- swap if your system uses a different slot
    male   = { drawable = 151, texture = 0 },
    female = { drawable = 187, texture = 0 },
}

Items show as missing during validation

On start, the resource validates every item referenced in shop prices and lootTables against ox_inventory's registry. If you see:

WARNING: The following items are NOT registered in ox_inventory: ...

You either skipped the bundled loot items in step 2 of Installation, or you customised lootTables to reference items your server doesn't have. Either merge them, register them, or remove the entries.

Sharks don't spawn

They're disabled by default. Set Config.Hazards.sharks.enabled = true and restart.

Debug commands

When Config.Debug = true, these are available:

The /divingmark -> /divingdump workflow is the fastest way to re-scout zones for a custom map: dive to a candidate position, run /divingmark, repeat 35–50 times, then /divingdump and paste straight into the zone's spawnPoints.

Discord support

If you've worked through the items above and still hit a wall, open a ticket in the medit8z Discord with:

• Your medit8z_diving version (fxmanifest.lua version line)
• The full server console output from start
• Whether you're on stock GTA V coastline or a custom map
• Whether the issue reproduces with the shipped config.lua

We respond fastest when those four things are in the first message.