Troubleshooting Guide

Common problems with oxide-newspaperjob and how to track them down.

Shift Problems

Can't clock in

Work through these in order:

1. Is the player standing right next to the depot worker? Clock-in only works within about 10 meters.
2. Is the depot full? Each depot takes a limited number of carriers at once (Config.MaxSlotsPerLocation, default 3).
3. Is the player already on shift?
4. Is the player suspended? Too many complaints means a temporary ban from the job — the menu will say so.

The shift menu doesn't open

1. Check the server console — did o-link start before oxide-newspaperjob?
2. Does the interaction prompt (third-eye / target) work on other scripts? If not, the problem is your targeting setup, not this script.
3. Did the depot worker actually appear? If not, see the next item.
4. Has the player fully loaded into a character? The depot doesn't activate until they have.

The depot worker doesn't appear

1. Check that the depot coordinates in Config.Locations weren't accidentally broken while editing.
2. If you changed Config.NpcModel, make sure the new model name is a real GTA ped model.
3. Check the server console for errors when the resource started.

Route Problems

No route appears after clocking in

1. Wait a few seconds and talk to the depot worker again — there's a short cooldown between route requests.
2. If you edited the houses, make sure there are still houses at the player's level (minLevel).
3. The player must be near the depot when the route is handed out — within about 15 meters.
4. The player must actually receive the weapon_newspaper item. If their inventory shows nothing, the item isn't set up — see the inventory section of Installation.

The map route or floating marker doesn't update

1. Confirm the route is still active (the on-screen overlay should be showing).
2. Check the F8 console (client side) for errors after a hit.
3. Make sure the web/dist files weren't deleted — see "UI Problems" below.

Throws aren't counting

1. The paper has to land close to the marked spot. The allowed distance shrinks at higher levels (hitRadius per level), so good players need to be more precise.
2. Houses must be delivered in route order — only the current house counts.
3. The player has to be reasonably close to the house when throwing — past Config.Throw.maxPlayerToTargetDist (80 meters by default), nothing counts.
4. If players are being told they're "too fast", see the next item.

Deliveries rejected as "too fast"

The server requires a minimum travel time per delivery, scaled by distance, to stop teleport cheats:

math.max(
    Config.Payment.absoluteMinDeliveryTime,
    distance * Config.Payment.minDeliveryTimePerDistanceUnit
)

If honest players are getting rejected (very fast vehicles, very close houses), lower minDeliveryTimePerDistanceUnit in shared/config/job.lua.

Paper / Inventory Problems

Players never receive newspapers

1. The weapon_newspaper item must exist in your inventory system — this is a required setup step, see Installation.
2. The item must keep its ammo count (the number of papers). On ox_inventory that's the throwable = true entry; on qb-inventory it requires the patch guide.
3. Make sure no other script is stripping items or weapons from players.

"Out of papers" triggers when the player still has papers

The script already guards against this — it double-checks the player's actual inventory before ending a route. If it still happens:

1. Check that your inventory is reporting item counts correctly through o-link.
2. Watch whether it happens right after moving the item between slots — if so, report it with that detail.

The newspaper item stays in the inventory after the shift

The item is removed on clock-out, death, bike loss, disconnect, and resource restart. If it lingers, item removal through o-link isn't working for your inventory — test whether other o-link scripts can remove items.

Bike Problems

The BMX doesn't appear

1. If you changed Config.Vehicle.model, make sure the new model exists on your server.
2. Check that the spawn point isn't blocked or inside something — set it fresh with the builder if in doubt.
3. The bike only spawns on clock-in, not when walking up to the depot.

No keys for the bike

Keys are handed out through o-link's vehicle key module. If the player can't ride the bike, check which key script your server runs and that o-link supports it — test whether other o-link scripts can give keys.

The bike counts as "lost" while the player still has it

The bike is treated as lost when it stops existing (destroyed or cleaned up) or when the player is on foot more than Config.Vehicle.bikeLostMaxDistance (300 meters) away from it.

1. Check whether another script is deleting unoccupied vehicles — that's the most common cause.
2. If players legitimately park far away and walk, raise the distance.

Pay and Progress Problems

No payout on clock-out

1. The payout only lands if the player completed at least one delivery and net pay was above zero after tax.
2. Check that money payments through o-link work — do other scripts pay players fine?
3. If a player disconnected mid-shift instead of clocking out, the unfinished shift isn't paid.

The payout looks wrong

The final number is built from several parts — check them against your config before assuming a bug: base pay per house, distance bonus, the level multiplier, the streak bonus, tips (paid separately in cash at the house), the speed bonus or late penalty, and tax taken at the end.

Progress isn't saving

1. Is oxmysql running and connected to the database?
2. Does the job_progression table exist? If not, run the install SQL — see Installation.
3. Look up the player's row (see Admin) and watch whether total_count rises after a delivery.

A player isn't leveling up

1. Compare their total_count in the database against the requiredDeliveries thresholds in shared/config/levels.lua.
2. Remember level 5 is the highest — there's nothing past Route Legend unless you add levels.

Streak questions

The daily streak counts real calendar days: deliver on consecutive days and it grows (one step per day, capped at 7 by default); skip a day and it starts over at 1. That's by design, not a bug.

UI Problems

The interface doesn't load at all

1. Check that web/dist/index.html and the web/dist/assets folder exist — if someone deleted them, re-download the resource.
2. Check the player's F8 console for errors.

The menu or summary gets stuck on screen

1. Check the F8 console for errors.
2. Try Config.menuStyle = 'menu' — if the plain menu works fine, the report should mention the NUI menu specifically.

The clock-out summary isn't what you expect

Config.shiftSummary = 'nui' shows the pop-up window; 'text' shows a notification. This setting only changes what appears on screen — the phone email is separate and is controlled by Config.usePhone.

Phone emails don't arrive

1. Config.usePhone must be true.
2. o-link's phone module must be set up for the phone script your server actually runs.
3. Some phone scripts don't support service emails — test whether other scripts can send emails through o-link.

Uniform Problems

There's no uniform option in the menu

1. Config.uniformsEnabled must be true (it ships false).
2. The option only shows while clocked in.
3. Restart the resource after changing the config.

The uniform doesn't apply, or the player's clothes don't come back

1. The shipped outfit values are placeholders — you must set real clothing values for your server first.
2. Clothing goes through o-link's clothing module; check it's working with your appearance script.

Turning On Debug Output

In shared/config.lua:

Config.Debug = true

This prints [oxide-newspaperjob] lines to the consoles for shift state changes, route generation, bike spawn/despawn, clock-in/out slot counts, and cleanup. It also draws a visible ring around the active house target, which is handy when tuning hit distances.

Deeper records — payouts, fines, anti-cheat rejections, admin actions — are written through o-link's logger. If your server runs oxide-logger (or another logging backend), you'll find them there under the oxide-newspaperjob resource name.

When Reporting an Issue

Include:

• your framework (QBCore, QBX, or ESX) and inventory script
• any errors from the server console
• any errors from the player's F8 console
• what the player was doing: clocking in, mid-route, losing the bike, clocking out
• steps to make it happen again, if you have them

Next Steps

• Installation
• Configuration
• Features
• Admin