# Troubleshooting Practical fixes for common setup and runtime issues. ## 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: ```text 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](#/docs/wd_phone/admin?section=check-your-installation) explains the report and the full `phoneadmin selftest`. ## Phone item does nothing 1. Check that Wolfden Phone and all required resources started without errors. 2. Check that the self-test report shows the framework and inventory you use (`framework selected: …`, `inventory selected: …`). Both must start before `wd_phone`. 3. 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. 4. 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. 5. Restart the server after adding or changing item definitions. 6. Test by using the item directly from inventory, then try the keybind. Keep the resource folder named `wd_phone`. See [Installation](#/docs/wd_phone/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: ```text phoneadmin signitems ``` [Item signatures](#/docs/wd_phone/admin?section=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](#/docs/wd_phone/upgrading) 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 <0-100>` and `phoneadmin power on`. See [Batteries & accessories](#/docs/wd_phone/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 `. ## 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/.json` and `locales/.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: ```text 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](#/docs/wd_phone/first-steps). ## 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 ` 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](#/docs/wd_phone/sims). ## 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](#/docs/wd_phone/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](#/docs/wd_phone/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](#/docs/wd_phone/clips?section=clips-live) needs the same relay. See [Video calls](#/docs/wd_phone/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](#/docs/wd_phone/communications?section=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](#/docs/wd_phone/media), 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](#/docs/wd_phone/device-operations?section=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](#/docs/wd_phone/shade)** is not in the store: it installs from a Shade SD card (`shade_sdcard`). Check that the item is in your inventory. - **[Racing](#/docs/wd_phone/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](#/docs/wd_phone/apps). ## 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](#/docs/wd_phone/wallet). ## 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](#/docs/wd_phone/music). ## 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](#/docs/wd_phone/music). ## A player forgot their PIN or password An authorized administrator can identify the device and clear a lockout or remove the PIN: ```text phoneadmin lookup phoneadmin unlockpin phoneadmin resetpin ``` `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 `. In game, `phoneadmin` opens the admin menu, which does the same without typing IDs. See [Admin tools](#/docs/wd_phone/admin) 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.