Troubleshooting Guide

Common problems and how to fix them, roughly in the order they tend to come up.

Clocking In

Make sure o-link starts before oxide-postaljob in your server.cfg.
Make sure your targeting resource (the "interaction eye") works elsewhere on the server — the supervisor uses the same system through o-link.
Check that the supervisor NPC is actually standing at the depot. If he's missing, see the next section.
The player must be fully loaded into a character. If they just joined, have them wait a few seconds and try again.

The supervisor NPC doesn't appear

Check the server console for errors from oxide-postaljob at startup.
If you edited shared/config/locations.lua, double-check the coords you entered.
If you changed Config.NpcModel, make sure the model name is valid.

Player can't clock in

The job refuses a clock-in when any of these are true — the on-screen message says which:

The depot is full (Config.MaxSlotsPerLocation players already working there).
The player is already on a shift.
The player is suspended from complaints — check with the SQL in ADMIN.md, or wait out the timer.
Another car or player is sitting on the van spawn point.
The player walked away from the supervisor mid-menu.

Loading the Van

The pallet doesn't appear (packages)

Check pickupPoints in the location config — each entry needs x, y, z, and a heading.
Make sure the spot isn't underground or inside a wall.

Can't pick up a box

All of these must be true:

The player is in the loading phase (just clocked in or just took a new task).
They aren't already carrying a box.
They're on foot, not in a vehicle.
The box still exists (a crew partner may have just taken it).

Boxes won't load into the van

Both rear doors must be open — this is the most common cause.
The player must be standing at the back of the van, close to it.
They must be carrying a box.

No post box prompt (letters)

The post box pickup is an invisible interaction zone at the configured spot, not a spawned object. Follow the map blip to the exact location and look around with the interaction eye.
Check postBoxes in the location config has valid entries.
The prompt hides while the player is already carrying the mail bag or sitting in a vehicle.

Deliveries

No route or blip appears after loading

Confirm every box (or the mail bag) actually got loaded — the shift only moves on when loading is complete.
Check deliveryZones (or letterBoxes) in the location config has entries the player's level qualifies for (minLevel).
Turn on Config.Debug = true and watch the console while reproducing.

Can't hand over a package

The player must grab a package from the van first (rear doors open, interaction eye on the van).
They must stand inside the glowing marker (within about 3 meters) — the "press E" hint appears when they're close enough while carrying.
They must be on foot.

No customer walks out

Customers only appear for package deliveries — letters go straight into the letterbox.
If you edited Config.CustomerPeds, make sure every model name is valid. If a model fails to load, the delivery still completes and pays — the handoff animation is just skipped.

The letterbox can't be targeted

Letter deliveries use an interaction zone at the configured coordinates, not the physical mailbox prop — stand right at the blip.
Only the current stop is active; letterboxes from earlier or later stops won't respond.
The player must be on foot.

The timer seems too short or too long

Timers are distance-based: Config.Timer.baseTime + Config.Timer.timePerDistanceUnit for every meter to the address. Adjust those two values in shared/config/job.lua. Remember a late delivery still pays — it just loses the bonus and takes a small penalty.

The Van

The van doesn't spawn

Check vehicleSpawn in the location config — it needs x, y, z, and a heading, on open ground.
If you replaced Config.Vehicle.model, make sure the model is valid and streamed on your server.

No keys / can't start the van

Your vehicle-key resource must be supported by o-link and working elsewhere on the server.
Confirm o-link starts before this resource.

"Van destroyed" mid-shift

This is intended behavior when the engine is wrecked (engine health below Config.Vehicle.destroyedThreshold). The current round is cancelled, a complaint is added, the fine is charged immediately, and the player has to ask the supervisor for a fresh task. The same happens if the van despawns or is deleted.

Partner can't see boxes in the van

Normal: box props inside the van are only drawn for the player who loaded them. The partner still has a synced count and can grab packages from the van as usual.

Crews

Can't send an invite

The inviter must be clocked in; the invitee must not be.
They must be within about 15 meters of each other.
The invitee can't already be in a crew or have another invite pending.
Wait a few seconds between attempts — invites have a short cooldown.

The partner never saw the invite

If the invitee has the supervisor menu open, the invite appears right in the menu. Otherwise they get a notification telling them to go to the supervisor — the invite expires after Config.Crew.inviteTimeout seconds (default 60).

Crew got out of sync

This usually traces to one of:

The partner was too far away when the van spawned (the van entity couldn't be found on their game). Have them drive to the van.
One member disconnected, died, or clocked out — the remaining member continues solo by design.

Pay and Progression

No money at clock-out

Pay is a single lump sum at clock-out — players are not paid per delivery during the shift.
Deductions (early-finish penalty, van damage, gas, taxes) can eat a small shift down to $0.
Check your framework's money system works through o-link elsewhere (e.g. other Oxide jobs pay fine).

Pay seems wrong

Walk through the deductions in the shift summary: early-finish penalty (clocked out with undelivered items), van damage charge, gas fee, and taxes. On the earning side, remember level multiplier, on-time/late status, streak bonus, tips, and the crew bonus all change per delivery.

The daily streak isn't counting

Streaks use real-world calendar days, not in-game days.
The streak ticks up once per day, on the first delivery of that day.
Skipping a day resets it to 1 (not 0).

Progress isn't saving

Confirm oxmysql is running and connected.
Confirm the job_progression table exists (re-run sql/install.sql — it's safe).
Look up the player's row using the SQL in ADMIN.md (job = 'postal').

Interface

Confirm web/dist/index.html and the files under web/dist/assets exist — they ship with the resource.
Press F8 and look for red errors when opening the menu.
As a test, set Config.menuStyle = 'menu'. If the simple menu works, the problem is isolated to the custom interface; if neither works, the problem is earlier (o-link, targeting, or the resource didn't start cleanly).

No pop-up summary at clock-out

The pop-up only shows when both are true: Config.shiftSummary = 'nui' and Config.menuStyle is not 'menu'. Otherwise the summary goes to the phone (or a simple notification in 'menu' mode).

No phone email with the summary

Config.shiftSummary must be 'text'.
Your phone resource must be one o-link supports for email (qb-phone, lb-phone, gksphone, okokPhone, qs-smartphone, yseries). On unsupported phones the emails simply don't arrive — players still get on-screen notifications for everything important.

Turning On Debug Logging

In shared/config.lua:

Config.Debug = true

The console will then print [oxide-postaljob] lines for shift state changes, clock-ins/outs, route generation, loading, payments, crew events, vehicle spawn/destruction, and progression changes. Turn it back off when you're done — it's chatty.

When Reporting an Issue

Please include:

your framework (QBCore, QBX, or ESX) and which phone/target/key resources you run
any errors from the server console
any errors from the client F8 console
exact steps to reproduce
whether it happened solo or in a crew