FiveM Phone Scripts Troubleshooting FAQ: 12 Common Issues Fixed

Phone scripts are the most feature-rich resources on a FiveM server. Messaging, calls, social media, GPS, camera, app store, dark mode — often a dozen apps in one bundle. The feature surface means more failure surface. When any single app breaks, the phone looks entirely broken to players.

This guide walks through the twelve phone script failures we see most often across qs-smartphone, npwd, lb-phone, and the QBCore/ESX defaults. Each section covers how to diagnose the root cause, the fix that resolves it in most cases, and the integration edge case that catches experienced admins.

Quick Diagnosis Table

Before diving into individual issues, match the symptom you see to the most likely root cause.

Symptom	Most likely cause	First thing to check
Keybind does nothing	Resource not started / no phone item	F8 console + inventory
Phone opens blank	NUI build skipped	npm run build in resource folder
Contacts empty	Identifier mismatch	SELECT owner FROM phone_contacts
Messages don't send	SQL schema mismatch	Server console for SQL errors
Camera black screen	screenshot-basic missing	ensure screenshot-basic
Social feed blank	App tables missing	Re-run phone SQL install
App store errors	App metadata drift	Re-run phone migration SQL
GPS does nothing	Other script clearing waypoints	HUD/minimap scripts disabled
Calls don't connect	VOIP resource integration	Voice resource ensure order
No notification sounds	NUI audio autoplay block	F8 devtools warnings
Dark mode doesn't persist	localStorage cleared	Store server-side instead
Custom app missing	App not in manifest	Grep resource for app name
Billing app broken	Event name mismatch	Billing resource events

Use this table as a triage filter. Once you've narrowed the bucket, jump to the detailed section below.

1. Phone Not Opening

When the phone keybind does nothing, start with the basics: is the resource running, is the NUI built, and does the player meet the phone's requirements?

-- Test in F8 console
start qs-smartphone  -- or your phone resource name

If this fails with couldn't find resource, the resource isn't installed. If it starts but the phone still doesn't open, check F8 for NUI errors.

Fix checklist, in order:

1. Resource is ensure-ed in server.cfg after your framework
2. NUI build step completed:

cd resources/[phone]/qs-smartphone/
npm install
npm run build

3. Player has a phone item in inventory (if required):

-- QBCore: qb-core/shared/items.lua
['phone'] = {
    ['name'] = 'phone',
    ['label'] = 'Phone',
    ['weight'] = 500,
    ['type'] = 'item'
},

4. No NUI errors in F8 console — press F8, open DevTools, check both Console and Network panels.

Modern phone scripts (qs-smartphone, npwd, lb-phone) all use React or Vue and require a build step. Skipping npm run build is the single most common install mistake.

2. Contacts Missing

Contacts live in a database table, typically phone_contacts or phone_contacts_<framework>. Verify the table is populated:

SELECT COUNT(*) FROM phone_contacts WHERE identifier = 'YOUR_IDENTIFIER';
DESCRIBE phone_contacts;

If the table exists but contacts don't load for a specific player, the identifier format has drifted. Servers that migrated from Steam hex to license IDs or to citizen IDs need to migrate their phone_contacts owner columns:

-- Example: migrate steam: to citizenid
UPDATE phone_contacts pc
JOIN players p ON p.identifier = pc.identifier
SET pc.identifier = p.citizenid
WHERE pc.identifier LIKE 'steam:%';

Always back up the table before running migrations.

3. Messages Not Sending

Message failures are almost always SQL errors in the phone_messages insert. Three common causes:

• Column name mismatch — the script expects sender_identifier but the table has senderIdentifier
• Missing NOT NULL column — a recent phone update added a read_status column that's NOT NULL with no default
• Foreign key violation — the receiver phone number isn't registered, so the FK constraint rejects the insert

Test a direct insert to isolate:

INSERT INTO phone_messages (sender, receiver, message, date)
VALUES ('1001', '1002', 'Test message', NOW());

If that works, the phone script is wrong. If it fails, the schema is wrong.

Enable SQL error logging in your server config so silent failures become loud ones.

4. Camera App Crashes

The phone camera uses screenshot-basic to capture and upload images. Without it, the camera crashes on first use.

# server.cfg
ensure screenshot-basic
ensure qs-smartphone

Configure screenshot-basic with an upload destination. Most phone scripts use Imgur, some use custom upload endpoints. Check the phone's camera config:

Config.ScreenshotResource = 'screenshot-basic'
Config.ScreenshotUploader = 'imgur' -- or 'custom'
Config.ImgurClientId = 'your-client-id'

A missing Imgur client ID produces a silent failure — the screenshot captures but never uploads. Watch the server console when taking a photo.

5. Social Media Not Loading

Twitter/Instagram clones in phone scripts are self-contained apps with their own tables. If the feed loads blank:

SELECT COUNT(*) FROM phone_twitter;
SELECT * FROM phone_twitter_accounts WHERE identifier = 'YOUR_IDENTIFIER';

If the table is missing entirely, re-run the phone script's SQL install file. Most phones bundle all app tables into a single phone.sql that creates everything — running it is safe (uses CREATE TABLE IF NOT EXISTS).

If tables exist but data doesn't show, check F8 DevTools Network tab for CORS errors or failed iframe loads. Some phones load social media apps in sandboxed iframes that need explicit permission.

6. App Store Errors

App store errors come from app metadata drift. Each installable app needs a valid entry:

Column	Required	Notes
name	Yes	Matches app folder
label	Yes	Display name
icon	Yes	Path to icon file
version	Yes	Semver string
enabled	Yes	Boolean
category	Varies	New in some phone versions
min_version	Varies	New in some phone versions

The most common cause is a phone update that added new columns without running the migration. Re-run the phone's migration SQL to align schema with the current version.

7. GPS Not Working

Phone GPS calls SetNewWaypoint(x, y) client-side. If setting a destination does nothing, verify the coordinates are valid:

-- Debug: log what the phone is sending
RegisterNUICallback('setWaypoint', function(data, cb)
    print(('[phone-gps] waypoint: %s, %s'):format(tostring(data.x), tostring(data.y)))
    SetNewWaypoint(data.x + 0.0, data.y + 0.0)
    cb({ ok = true })
end)

If coordinates log correctly but the waypoint doesn't appear, another script is clearing it. HUD replacements and custom minimaps are the usual culprits — they call DeleteWaypoint on their own update loop. Disable them temporarily to isolate.

8. Phone Calls Dropping

Phone calls depend on your VOIP resource (pma-voice, mumble-voip). Verify the integration:

-- Phone config
Config.VoiceResource = 'pma-voice'
Config.EnableVoiceCalls = true

Fix checklist:

1. Voice resource is ensure-ed BEFORE the phone in server.cfg
2. Voice resource's exports match what the phone expects
3. Phone version matches voice resource version (pma-voice had breaking changes in v6)
4. Player's mic permissions granted in Cfx settings

If calls connect (ringing works) but audio is silent, the voice resource isn't opening a private call channel. This is usually a version mismatch — the phone is calling an export that the voice resource renamed.

9. Notification Sounds Missing

Notification sound failures have three causes:

• Files missing from resource — check the phone's audio/ or html/sounds/ folder
• Not declared in fxmanifest.lua — the files block must include audio paths:

files {
    'html/**/*',
    'html/sounds/*.mp3',
    'html/sounds/*.ogg',
}

• NUI audio autoplay blocked — modern Chromium NUI blocks audio until user interaction. Watch F8 DevTools for:

play() failed because the user didn't interact with the document first

Most phones handle this with an on-load click, but custom forks often break it.

10. Dark Mode Issues

Dark mode is a pure NUI toggle — a CSS class on the root element. If clicking the toggle does nothing:

1. Check F8 DevTools Console for JavaScript errors on click
2. Inspect the root element to see if the dark class is being added
3. If the class is added but nothing visually changes, the stylesheet doesn't define dark mode selectors

If dark mode toggles correctly but resets between sessions, the phone is storing the preference in localStorage — NUI localStorage gets cleared between resource restarts. Fix by storing the preference server-side:

CREATE TABLE phone_settings (
    identifier VARCHAR(50) PRIMARY KEY,
    dark_mode BOOLEAN DEFAULT FALSE,
    notifications_enabled BOOLEAN DEFAULT TRUE
);

Load on phone open, save on toggle.

11. Custom Apps Not Appearing

Custom apps need three things, all in sync:

1. Config entry — in the phone's app config, matching the folder name
2. Files present — HTML/JS at the path declared in config
3. Manifest inclusion — in fxmanifest.lua's files block so NUI serves them

-- fxmanifest.lua must include custom app files
files {
    'html/apps/my-custom-app/**/*',
}

Missing any one makes the app invisible. Grep the phone resource for your app name:

grep -r "my-custom-app" resources/[phone]/qs-smartphone/

You should see hits in config, fxmanifest.lua, and the app folder itself.

12. Billing App Not Working

Phone billing apps bridge to a separate billing/invoicing resource. The three most common: okokBilling, qb-banking, esx_billing.

-- Phone billing config
Config.BillingResource = 'okokBilling'
Config.BillingEvents = {
    send = 'okokBilling:server:SendInvoice',
    list = 'okokBilling:server:GetInvoices',
    pay = 'okokBilling:server:PayInvoice',
}

Event names must match on both sides. If the billing resource renamed an event in a recent update, your phone stops working silently. Trace the events:

-- Phone side: log what it's emitting
RegisterNUICallback('sendInvoice', function(data, cb)
    print(('[phone-billing] emit: %s'):format(Config.BillingEvents.send))
    TriggerServerEvent(Config.BillingEvents.send, data)
    cb({ ok = true })
end)

If the emit logs but the billing resource never receives it, check the receiving handler's registered event name for a typo or rename.

Recommended Scripts

When you need a phone script that just works — framework-native, actively maintained, documented — check the VertexMods catalog:

• FiveM Phone Scripts — Premium and free phone resources
• Best FiveM Scripts 2026 — Top-rated scripts across all categories
• FiveM Troubleshooting Guide — Broader troubleshooting playbook
• FiveM Error Codes Fixes — Decoding common error messages