Troubleshooting

Startup Issues

Resource Fails to Start

Symptoms: Server console shows errors on startup. Resource does not appear in resource list.

Solutions:

1. Check dependency order in server.cfg

ensure ox_lib
ensure oxmysql
ensure community_bridge
ensure oxide-weaponprinting

All three dependencies must start before oxide-weaponprinting.

2. Verify database connection — Make sure oxmysql is connected and sql/install.sql has been imported. Check for errors like [oxmysql] Table '3d_printers' doesn't exist.

3. Verify community_bridge is working — Check that community_bridge detects your framework. Look for its startup messages in the console. If you do not have community_bridge installed, download it from the community_bridge Discord.

4. Check for missing stream files — The resource includes custom streamed props. If you see model loading errors, verify the stream/ folder is intact with all .ytyp and .ydr files.

Items Not Usable

Symptoms: Using a 3D printer or weapon bench item does nothing. No error in console.

Solutions:

1. Verify items are registered — All items listed in Installation > Item Registration must exist in your framework's item database.
2. Check that items are marked as useable — QBCore: useable = true in the item definition. The 3d_printer, weapon_bench, and placeable_table items must be useable.
3. Check for bridge errors — Look for RegisterUsableItem errors in the console from community_bridge.
4. Verify item names match exactly — Item names are case-sensitive. 3d_printer is not the same as 3D_Printer.

---

Placement Issues

Cannot Place Equipment

Symptoms: Ghost prop appears but placement fails. "Cannot place here" error.

Solutions:

1. Check safe zones — If you are in a configured safe zone, placement is blocked. Check Config.SafeZones in shared/config.lua.
2. Check per-player limits — If you have reached Config.MaxPerPlayer limits (printers: 3, benches: 2, tables: 5), remove an existing piece of equipment first.
3. Check inventory — The item must be in your inventory. If you used it but it was not consumed, there may be an inventory bridge error.

Cannot Pick Up Equipment

Symptoms: Interaction option to remove equipment does not appear or fails. "Not your equipment" error.

Solutions:

1. Check ownership setting — When Config.RequireOwnership = true (default), only the player who placed the equipment can remove it.
2. Check inventory space — You need enough inventory space to receive the item back.
3. Verify you are close enough — You must be within 4 meters of the equipment to pick it up.

---

Printing Issues

USB Fails to Load (Malfunction)

Symptoms: USB is consumed but no blueprint appears. "USB malfunction" message.

This is intended behavior. The base malfunction chance is 25%, reduced by player level and cooling upgrades.

1. Level up to reduce malfunction chance (1.5% reduction per level)
2. Install cooling fan upgrades on the printer (-10%, -20%, -30% per tier)
3. Adjust the config if the rate is too high:

Config.UsbMalfunction = {
    baseChance = 25,       -- Lower this value
    levelReduction = 1.5,  -- Increase for faster reduction per level
    minimumChance = 5,     -- Minimum chance floor
}

Print Does Not Start

Symptoms: Selecting a part to print does nothing. No filament consumed.

Solutions:

1. Check filament supply — You need enough printer_filament items in your inventory. Each part has a different filament cost.
2. Check blueprint level requirements — Your player level must meet the minimum for that blueprint. See Config.Progression.blueprintLevels.
3. Check for active print — A printer can only run one print job at a time. Wait for the current print to finish and collect it.

Cannot Collect Finished Print

Symptoms: Print shows as complete but collection fails.

Solutions:

1. Check inventory space — You need enough space for the printed part item.
2. Verify you are close enough — You must be near the printer to interact with it.
3. Check the printer is not locked — If another player is using the printer, it may be locked. Wait for them to finish.

---

Assembly Issues

Cannot Assemble Weapon

Symptoms: Weapon recipe is grayed out or does not start. "Missing parts" error.

Solutions:

1. Verify all required parts are in inventory — Each weapon requires specific parts. Use /give_parts [name] to check what is needed.
2. Check assembly level requirements — Your player level must meet the minimum for that weapon. See Config.Progression.assemblyLevels.
3. Verify you are interacting with a weapon bench — Assembly only works on weapon benches, not 3D printers.

Weapon Not Received After Assembly

Symptoms: Crafting animation plays, parts are consumed, but no weapon appears.

Solutions:

1. Check inventory space — Weapons are added to your inventory. If your inventory is full, the weapon may not be added.
2. Check server console — Look for errors related to AddItem or inventory operations.
3. Verify the weapon name is valid — Check that the weapon field in Config.Assembly matches a valid GTA weapon hash (e.g., weapon_pistol).

---

Durability Issues

Weapon Does Not Degrade

Symptoms: Firing a 3D-printed weapon does not reduce durability. No jam mechanics.

Solutions:

1. Verify the weapon has printed metadata — Only weapons with metadata.printed = true and metadata.durability are tracked. Weapons from other sources are not affected.
2. Check sync interval — Durability syncs every Config.Durability.shotSyncInterval shots (default: 10). Fire at least 10 shots before checking.
3. Enable debug mode — Set Config.Debug = true and check console for durability sync messages.

Weapon Breaks Unexpectedly

Symptoms: Weapon disappears from inventory during use.

Solutions:

1. Check durability before use — The inventory tooltip shows current durability. Weapons at 0% are destroyed if Config.Durability.breakAtZero = true.
2. Disable weapon breaking:

Config.Durability.breakAtZero = false

3. Adjust degradation rate:

Config.Durability.degradePerShot = 0.15  -- Lower this for slower degradation

---

Upgrade Issues

Cannot Install Upgrade

Symptoms: "Requires PSU" or "Requires level X" error.

Solutions:

1. Check PSU requirements — Higher-tier upgrades require a sufficient Power Supply. Install PSU Mk I before Mk II upgrades, and PSU Mk II before Mk III upgrades. See Features > Printer Upgrades for the full dependency chain.
2. Check level requirements — Each upgrade tier has a minimum level. See Config.Progression.upgradeLevels for the exact requirements.
3. Verify upgrade item is in inventory — You need the specific upgrade item (e.g., printer_nozzle_mk2). The upgrade consumes the item on installation.
4. Check current tier — Upgrades must be installed in order: Mk I, then Mk II, then Mk III. You cannot skip tiers.

---

NUI Issues

Printer/Bench NUI Does Not Open

Symptoms: Interacting with equipment does nothing. No UI appears on screen.

Solutions:

1. Verify the web build exists — Check that web/dist/index.html exists. If not, rebuild:

cd oxide-weaponprinting/web
npm install
npm run build

2. Check the browser console — Press F8 in-game, then check for JavaScript errors in the NUI browser.

3. Verify the DUI screen HTML exists — The printer uses a DUI screen at web/dui/screen.html. Verify this file exists.

DUI Screen Not Displaying on Printer

Symptoms: Printer model appears but the screen is blank.

Solutions:

1. Verify DUI file exists — Check that web/dui/screen.html is present in the resource.
2. Check that the file is listed in fxmanifest.lua:

files {
    'web/dist/**/*',
    'web/dui/screen.html',
}

---

General Debugging

Enable Debug Mode

Config.Debug = true  -- in shared/config.lua

This will output detailed information to the server console with the [oxide-weaponprinting] prefix, including:

• Equipment loading counts on startup
• Active print restoration
• Level up notifications
• Upgrade installations
• Weapon durability events

Check Rate Limiting

If actions seem to be ignored silently, you may be hitting the server-side rate limit. Default cooldowns:

Action	Cooldown
Place/remove equipment	3000ms
Load USB	2000ms
Start/collect print	3000ms
Install upgrade	2000ms
Start/complete craft	3000ms
Select/remove blueprint	1000ms

---

Getting Help

When reporting issues, include the following information:

• Server framework (ESX, QBCore, QBx, etc.)
• community_bridge version
• ox_lib version
• Error messages from the server console (F8 or terminal)
• Steps to reproduce the issue
• Debug mode output if available
• Whether the issue involves printing, assembly, durability, or upgrades