Troubleshooting

Work through the symptoms that match your problem. Each fix is something you can do right now. If nothing here helps, see Getting Help at the bottom.

Startup & Loading Issues

The resource won't start or errors on boot

Symptoms:

• The console shows errors mentioning oxide-shops when the server starts.
• Shops never appear.

Solutions:

1. Check the load order. o-link must start before oxide-shops in your server.cfg. So must your framework and oxmysql. See Load Order.

2. Confirm the dependencies are running. ox_lib, oxmysql, and o-link must all be started and free of their own errors. If any of them failed, oxide-shops can't work.

3. Confirm the database is connected. oxide-shops creates its own tables on first start. If your oxmysql connection string is wrong, this fails. A working framework means the connection is fine.

4. If your database user can't create tables, import sql/install.sql by hand (see Database Setup), then restart.

Shops Not Appearing

No shop blips or shopkeepers on the map

Symptoms:

• The map has no store/gun-shop/barber blips.
• There are no shopkeepers to talk to.

Solutions:

1. Make sure you've joined as a character. Shops load for you once your character is fully loaded, not at the login screen.

2. Check that shops have actually been created. A fresh install starts with an empty map — shops only appear after an admin creates them from the built-in templates in /shop admin (see INSTALLATION.md). Watch the console with debug on (see General Debugging) for a line like Loaded N shops — if it says Loaded 0 shops, no shops have been created yet.

3. Check the blip isn't hidden. A specific shop's blip may have been hidden in /shop admin. That only affects the map icon — the shopkeeper is still there.

One shop's blip is missing but the shopkeeper is there

This is expected if the blip was hidden for that shop. Open /shop admin, find the shop, and use the Map Blip editor to turn the blip back on.

A shopkeeper is there but pressing my key does nothing

Symptoms:

• You see the shopkeeper but get no Browse Shop prompt.

Solutions:

1. Confirm your target resource is running. The interaction prompt comes from ox_target (through o-link). If it isn't started, no shop can be opened.

2. Stand closer. You must be within the interaction distance (Config.InteractionDistance, 2.5 m by default).

3. Check the shop isn't job-locked against you. If the shop is restricted to a job/rank/duty you don't have, its options are hidden. See Access restriction.

Buying & Selling Issues

"You don't have enough money"

The item price plus sales tax is charged from the player's cash (shop purchases and pawn/service purchases use cash; buying a whole shop uses bank). Make sure the player has enough in the right account.

A player can't buy an item / the item shows its raw name

Symptoms:

• An item is listed by its code name (like weapon_pistol) instead of a friendly label.
• Buying it fails.

Solutions:

1. Register the item in your framework. Every item a shop sells must exist in your framework's item list (and, for ox_inventory, have a definition). An unregistered item shows its raw name and can't be given to the player.

2. Check the player can carry it. If the player's inventory is full or over weight, the sale is refused and no money is taken.

"You're too far from the shop"

This is an anti-cheat guard. The server rejects a shop action from farther than Config.ServerInteractDistance (12 m by default). If legitimate players hit this at a shop with an unusual interior or camera, raise ServerInteractDistance a little in /shop settings.

A shop refuses to serve a player

Symptoms:

• "This store doesn't serve you".

Cause: the shop is locked to a job, minimum rank, and/or on-duty status. Only players who match are served. Open /shop admin, find the shop, and adjust or clear its access restriction. A shop with no job set serves everyone.

Service Shop Issues (Barber, Tattoo, Clothing, Mask)

The barber says it can't style hair

Symptoms:

• "The barber can't style hair on this server's clothing system".

Cause: your clothing/appearance resource doesn't expose full hair and face detail through o-link. The barber refuses rather than wipe the player's look.

Solution: use an appearance-rich clothing resource (for example illenium-appearance, fivem-appearance, or rcore_clothing). Confirm it's installed and started before o-link.

A player-owned service shop says it's out of supplies

Symptoms:

• "This shop is out of supplies" (or "This barber shop is out of supplies").

Cause: player-owned barber/tattoo/mask/clothing shops consume a supply item per service (hair_product, tattoo_ink, mask_blank, fabric). The shop has run out.

Solutions:

1. The owner should restock via the wholesale option in Manage Shop.
2. Confirm the supply items are registered in your framework (see Adding the Supply Items). If they aren't, owners can't stock them and the shop can never serve.

A tattoo isn't showing in the parlor

Symptoms:

• Some tattoos are missing from the shop menu.

Cause: a tattoo only appears if it has a preview camera set. The default collections ship with cameras; any tattoo you add yourself starts with none and is hidden until set.

Solution: open /shop admin at a tattoo shop and use the tattoo camera editor to set the missing tattoo's camera.

Admin & Settings Issues

/shop admin or /shop settings says I don't have permission

Symptoms:

• "You don't have permission to do that".

Solution: grant the player admin access. See Permissions. The quickest fix is the two add_principal / add_ace lines in your server.cfg.

The menu won't open from the server console

This is expected. /shop admin and /shop settings open on-screen menus, so they only work for a player in-game, never from the console.

"In-world placement needs an updated o-link"

Cause: this message comes only from the /shop settings editor, when you try to place a template's location in the world — that path needs a newer o-link feature. Placing a shop's location or chairs in the /shop admin panel uses its own built-in placement tool and does not show this message.

Solution: update o-link to the latest version and restart. In the meantime, you can still place shop locations and chairs from /shop admin.

Configuration Changes Not Applying

I edited a config file but nothing changed

Symptoms:

• You changed a value in shared/config.lua (or another config file) but the game still uses the old value.

Cause: this is by design. After the first start, oxide-shops stores its settings in your database, and the database is the source of truth. Hand-edited file changes are ignored (except a brand-new setting the first time it appears).

Solution: change the setting in /shop settings instead. It applies immediately and is saved. See How Configuration Works.

I want to wipe all settings back to the file defaults

Each setting has a Reset to default button in /shop settings that restores the value the resource shipped with. To reset everything, you can clear this resource's rows from the oxide_settings database table (where resource = 'oxide-shops') and restart — the file defaults will be re-imported on the next boot. Only do this if you're comfortable editing your database.

Auction Issues

A player didn't get their winnings / refund / sold item

This is usually not a bug. Auction payouts, refunds, won items, returned items, and won vehicles are delivered the next time the player logs in if they were offline (or couldn't carry an item) at the moment the auction settled. Ask the player to relog. If an item couldn't be carried, they need free inventory space when they log in.

A vehicle auction was voided

Symptoms:

• "Auction was voided" and the bidder was refunded.

Cause: the vehicle's ownership is re-checked at the moment of sale. If the seller no longer owns the car (they sold or traded it), or ownership can't be transferred, the auction is cancelled and the top bidder is refunded. This is a safety feature to stop duplicated or stolen vehicles.

General Debugging

Enable Debug Mode

Turn on debug logging to see extra detail in the server console:

1. Open /shop settings.
2. In the General group (Advanced tier), turn Debug logging on and save.

This prints extra [oxide-shops] lines to the server console — shops loaded, purchases, and errors. Turn it off on a live server when you're done.

Getting Help

If none of the above resolves your issue:

1. Turn on debug mode and reproduce the problem.
2. Check your server console for error messages (look for lines mentioning oxide-shops, o-link, or oxmysql).
3. Note which framework and clothing/target resources you run.
4. Contact Oxide Studios support with your debug output and those details.