Common Issues

The phone doesn't open at all

Almost always start order. oxmysql is the phone's only hard dependency and must be up first:

ensure oxmysql
ensure es_extended        # or qb-core / qbx_core
ensure your_inventory
ensure [phone]

If the console shows a SearchPhoneItems error, the phone reached the inventory but got nothing back. Either the order above is wrong, or your inventory isn't wired up — see Custom inventory.

Also confirm the player is actually carrying a phone or iphone item. The phone is item-gated unless you set Config.ItemRequire = false.

Taking a photo does nothing

The media tokens in gksphone/config/serverconfig.lua are still the placeholder:

Cfg.MediaService   = "fivemanage"
Cfg.AuthTokenImage = "API_TOKEN"   -- replace this

This is the single most common miss on a fresh install. See Installation → Configure the server side.

Error: Media not found

Same cause — the media section in serverconfig.lua is incomplete or the token is wrong for the service you picked.

My cursor is stuck in the center

Enable raw input in your GTA game settings.

I denied microphone access, how do I enable it again?

Close FiveM completely, delete AppData\Roaming\CitizenFX\media_access.json, then reconnect. You'll be prompted again.

Video calls connect then drop

NAT traversal is failing. The default config is STUN-only, which fails for roughly one connection in five — mobile data, corporate firewalls and some VPNs all block direct peer-to-peer. Add a TURN server or switch to Cloudflare mode: WebRTC.

The battery never drains, charging stations do nothing

The battery system ships off. Set ChargeOn = true in gksphone/config/charge/config.lua — see Charge.

Wrong theme — iOS instead of Android

The theme follows the item, not a setting:

Remap them in Config.ItemName if you want it the other way round.

I hid an app but it's still on the phone

show: false alone isn't enough for an app that has a placement flag. For the four dock apps — Phone, Messages, Mail, Camera — you have to write both startapp: false and startbottom: false explicitly. Deleting the lines doesn't work, because the check is for the value false. See Apps.

A music upload is accepted then rejected

The interface and the server check different settings. Music.maxDuration in config.json governs what the app accepts; Config.MusicMaxDuration in config.lua is what the server enforces. Set both to the same value.

Real App QR login doesn't work

Check Config.RealAppJoinCode. On start the phone strips a full URL back to the join code and warns, but a code containing anything other than letters and digits is rejected and blanked, which disables Real App login silently. The console tells you which happened. See Real App.

Modded car names show as NULL in the Garage app

The vehicle has no label registered. Add one in your vehicle resource:

Citizen.CreateThread(function()
    AddTextEntry('challenger16', 'Dodge SRT Demon')
end)

The name must match <modelName> in the vehicle's vehicles.meta:

<modelName>challenger16</modelName>
<gameName>challenger16</gameName>

For a bulk fix across many vehicles:

Console: Version not found in fxmanifest.lua

gksphone/fxmanifest.lua lost its version line. Restore it from the download — the phone reads it for update checks.

Still stuck?

Turn on Config.Debug = true in gksphone/config/config.lua for verbose logging, reproduce the problem, then bring the console output to Discord. Turn it back off afterwards — debug builds also register test commands.