Troubleshooting · Wolfden Phone

Start with the self-check

About five seconds after Wolfden Phone starts, the server console prints a short boot self-check: a count of passed checks and one line for each warning, with its fix. For the full read-only report, run this in the server console:

phoneadmin selftest report

It shows the framework and inventory it selected, missing items, the database version, the media host, the video call relay, missing language files and the server secret. Most setup problems below show up there first. Admin tools explains the report and the full phoneadmin selftest.

Phone item does nothing

Check that Wolfden Phone and all required resources started without errors.
Check that the self-test report shows the framework and inventory you use (framework selected: …, inventory selected: …). Both must start before wd_phone.
Confirm the phone entries are in your inventory's item list: ox_inventory/data/items.lua, or QBShared.Items in qb-core/shared/items.lua for qb-inventory. Phone items are named by colour, such as nova_phone_ocean; a plain nova_phone item does not open.
On ox_inventory, check client.export = 'wd_phone.usePhone' in that entry. On qb-inventory, check useable = true and that qb-inventory is 2.1.0 or newer.
Restart the server after adding or changing item definitions.
Test by using the item directly from inventory, then try the keybind.

Keep the resource folder named wd_phone. See Installation for the complete item entries.

"This phone could not be verified"

The item's signature does not match, so the phone refuses to start. This happens to items that were edited or forged, and to every item in use after the server's signing key changed, such as after changing wd_phone:secret or moving to a database without the old key. To sign the items players carry again, run this from the server console while they are online:

phoneadmin signitems

Item signatures explains which items this reaches. If a new phone answers that it can't start yet, the server has no signing key: import migrations/install.sql and check the self-test's server secret line. See Updating Wolfden Phone to keep the key across updates.

Item images are missing

Copy every .png from wd_phone/inventory/ into ox_inventory/web/images/, or qb-inventory/html/images/ for qb-inventory. On ox_inventory, check that each item entry has its client.image. Restart the inventory.

The keybind does not work

The default key is M. Rebind it under FiveM → Settings → Key Bindings → FiveM. Existing player keybinds may override a new Config.OpenPhoneKey value. Also check that the player carries a phone item and is not dead or cuffed.

The phone is off

The battery is empty, or the player turned the phone off with its side button.

"Connect to power": charge the phone with a car charger, power bank or charging pad; it turns back on by itself at 3%. To turn batteries off, set Config.Charging.enabled = false.
Turned off by hand: the phone stays off, even while charging, until the player turns it on again from its off screen.

An admin can also set the battery or turn a phone on with phoneadmin battery <deviceId> <0-100> and phoneadmin power <deviceId> on. See Batteries & accessories.

The phone shows only a lost screen

The phone is in lost mode. Its Nova Account password unlocks it, or the owner can turn lost mode off in Locate. An admin can clear it with phoneadmin found <deviceId>.

The phone is blank or white

Check that web/dist/index.html and its assets and locales folders were uploaded. If anything is missing, extract the resource again from your download; the interface needs no build step. Check F8 for missing asset or script errors, then restart the resource after correcting the files.

A language shows English

The language's file is missing or not valid JSON. The boot self-check and phoneadmin selftest report name it. Every language in Config.Languages needs both web/dist/locales/<code>.json and locales/<code>.json, and any file in the overrides/ folders must be valid JSON. Text missing from a file shows in English.

Text the server writes, such as prompts, shop menus and the notifications the server sends to phones, uses one language for the whole server: ox_lib's language setting (setr ox:locale "de" in server.cfg), not the phone's. The language picker in Settings changes the phone screen only. Echo, Snapgram and Ember notifications are always in English.

Database or feature unavailable errors

Missing schema can make the store, backups or Locate appear unavailable. From the server console, run:

phoneadmin schema

Back up your database, stop the resource and import the included migrations/install.sql into the correct database. Start the resource and check again. Use the installer shipped with your current resource version. The database must be MariaDB 10.3 or newer; the self-test checks the version.

New phone shows No SIM

This is normal. Visit a carrier shop, activate a SIM and install it in SIM Manager. New phones do not get a number automatically with the default configuration. Follow First setup.

SIM or eSIM will not activate

Confirm the phone supports the SIM and has a free slot.
Check that an eSIM code has not already been used or expired; codes expire after 15 minutes by default.
Wolfden Phone Pro allows two enabled lines, while Wolfden Phone allows one.
Wolfden Phone Secure accepts only Ghost Mobile eSIMs, and Ghost Mobile sells nothing else.
Check prepaid credit, overdue bills and burner eSIM expiry.

Use the error displayed by the phone to narrow down the cause. Do not delete all SIM rows as a troubleshooting shortcut.

No Service where there should be coverage

Signal comes from cell towers. A tower can be switched off, or sabotaged by players and waiting for a repair crew. As an admin, run phoneadmin towers in game to open the tower editor and its coverage view, or in the server console to list every tower and its status. phoneadmin towerrepair <towerId> brings a damaged tower back. Also check airplane mode.

An app says it has no data

Messages, Mail, the Wallet, social apps and Nova Store need mobile data or Wi-Fi. The app's error says why: airplane mode, Mobile Data switched off, no SIM, no service, a suspended line, or no data left. Buy a data pack or top up in SIM Manager, or join Wi-Fi. See SIMs & carriers.

Personal Hotspot gives no internet

Phones on a Personal Hotspot use the host's mobile data. The host needs Mobile Data on, a SIM with service and data left, and must carry the phone, switched on and out of airplane mode. The host's Settings → Personal Hotspot says why joined phones have no internet. A hotspot takes five phones by default, and Wolfden Phone Secure cannot share one. See Batteries & accessories.

The records terminal refuses a search

Only the jobs in Config.SubscriberRecords.jobs (police by default) can search, on duty, standing at the terminal. Check the officer's job and duty, and that the terminal's coords in config/records.lua match your map. See Subscriber records.

Calls connect but there is no audio

Confirm pma-voice is running before Wolfden Phone. Test with two connected players, check their voice setup and confirm both phones have coverage. Call quality changes with signal; No Service can prevent or end a call.

Video call buttons are greyed out

No TURN relay is configured. Run phoneadmin relay in the server console: it says what is missing. Clips Live needs the same relay. See Video calls.

Emergency calls do not reach dispatch

Emergency calls and Services requests go to the first started supported dispatch resource. Check that yours is running before wd_phone, or name it in config/dispatch.lua or with set wd_phone:dispatch in server.cfg. Supported: ps-dispatch, cd_dispatch, cd_dispatch3d, qs-dispatch, rcore_dispatch, core_dispatch and lb-tablet. See Emergency calls and dispatch.

Messages are not arriving

Check the recipient number, enabled SIM, signal, airplane mode, data and block lists. Messages wait for service and fail if not delivered within 60 seconds. Press and hold, or right-click, a failed message to retry.

Photos and videos are not saved

"Upload unavailable" means no media host is configured. Add a Fivemanage key or set up self-hosting, then run phoneadmin selftest report. See Camera & media hosting, which also covers broken images and failed video uploads.

A camera may also refuse to open while another resource's scripted camera is active.

Face Unlock does not work

Face Unlock needs a PIN, and does not work with a mask on. After the phone turns on, or after too many failed scans, the PIN is needed once. Changing or removing the PIN deletes the enrolled faces, so set Face Unlock up again in Settings → Security. Wolfden Phone Secure has no Face Unlock. See PIN and Face Unlock.

An app is missing

New phones download Nova Wallet, Echo, Snapgram, Ember, Clips, Rides, Bites, Garage, Homes, Radio, Arcade, Marketplace, Business, City and Routers from Nova Store.

Shade is not in the store: it installs from a Shade SD card (shade_sdcard). Check that the item is in your inventory.
Racing is hidden until the player carries a Racing USB (racing_usb), unless you turn Config.Racing.requireItemForApp off.
Wolfden Phone Secure has a fixed set of apps and no store.

See Apps & appearance.

Wallet balance or payments are wrong

Nova Wallet shows the player's real bank. Check that your banking resource starts before wd_phone and that wd_phone:bank names it. QBCore and ESX can only pay players who are online. See Wallet & payments.

Music has no stations or songs

This is expected: the release ships no radio stations or songs. Add streams and songs you have the rights to. See Music & speakers.

Music is not heard by others

Music plays privately in paired NovaBuds. Otherwise, the phone speaker is quiet and heard only within 8 metres, and barely through walls; a Bluetooth speaker carries much further. The range is Config.Music.phoneSpeaker in config/music.lua. If a song link does not play at all, check that it is a direct https audio link and allowed by linkHosts. See Music & speakers.

A player forgot their PIN or password

An authorized administrator can identify the device and clear a lockout or remove the PIN:

phoneadmin lookup <serverId>
phoneadmin unlockpin <deviceId>
phoneadmin resetpin <deviceId>

unlockpin clears a lockout; it does not change the PIN. Check the device ID before using resetpin; it also removes the phone's enrolled faces. For a forgotten Nova Account password, use phoneadmin accountpw nova <email> <newPassword>. In game, phoneadmin opens the admin menu, which does the same without typing IDs. See Admin tools for the permission and every command.

Preparing a support report

Include your Wolfden Phone version, the exact error, what you expected, the steps to reproduce it and whether it affects new or existing phones. Note the framework, inventory, voice, banking and media host involved. The output of phoneadmin selftest report helps.

Include relevant server console and F8 errors. Remove database passwords, API keys and relay secrets before sharing logs. Use the support channel associated with your purchase; this site does not submit tickets.