Troubleshooting

Start with the first failing layer. Do not change UI code to work around a database, framework, resource-order, or manifest problem.

Diagnostic order

1. Confirm resource start order.

2. Check the server console for Lua, JavaScript, and SQL errors.

3. Check the client F8 console.

4. Verify the selected framework and bridge mappings.

5. Verify the database schema.

6. Reproduce with built-in applications before testing a custom application.

7. Rebuild web assets only when source files changed.

Phone does not open

Check:

• src-phone is started.

• web/dist/index.html exists and is included by fxmanifest.lua.

• /tel works even if the configured key does not.

• Config.PhoneOpenKey contains a valid FiveM mapping name.

• The player does not have a conflicting saved key binding.

• The client console does not report a missing phone prop or NUI file.

If /tel works but the key does not, reset or change the local FiveM key binding. Restarting the resource does not overwrite a player's existing local mapping.

Missing-table or unknown-column errors

Cause: install.sql was not imported completely, or an older schema was not migrated.

Resolution:

1. Stop src-phone.

2. Back up all src_phone_% tables.

3. Import the current complete install.sql.

4. Review the first SQL error rather than continuing through the remaining failures.

5. Restart the resource.

See Database.

Phone number or mail address is missing

Check that:

• Framework player-loaded events are reaching the bridge.

• The configured framework identifier is non-empty.

• src_phone_data exists and is writable.

• Config.PhonePrefix, Config.PhoneNumberLength, and Config.MailDomain are valid.

• No unique-value conflict exists from a manually edited number.

Calls connect without voice

Check:

• The configured voice resource starts before src-phone.

• BridgeConfig.Call.VoiceSystem matches the running voice integration.

• Both players have valid phone numbers.

• The voice resource supports the channel operations expected by the bridge.

• Speaker mode is tested separately from the normal private call channel.

A working call UI does not prove that the voice bridge joined the players to the same channel.

Camera opens but upload fails

Check:

• Config.FivemanageApiKey is set in shared/server_config.lua.

• The token is active and permitted to upload the requested media type.

• The server can reach the upload provider.

• Payload limits are not exceeded.

• The key has not been placed in client-visible configuration.

Do not post the token in a support message. Rotate it if it has been exposed.

Garage is empty or shows incorrect state

Check BridgeConfig.Garage.SQL against the actual vehicle table:

• Table name.

• Owner identifier column.

• Plate and model columns.

• Stored/out/impound state column and values.

• Fuel, engine, body, and mods columns when used.

Also verify that the selected garage, key, and fuel resources match their bridge configuration.

App reports no internet

Check:

• Airplane mode is disabled.

• Wi-Fi is enabled and the character is connected to an authorized router within range.

• The router has remaining quota.

• Cellular data is enabled, valid, and has remaining quota.

• Config.Router.InternetUsageEnabled and Config.Cellular.Enabled match the intended server rules.

• Streaming usage values are not consuming the quota faster than expected.

An external application with requiresInternet: true uses the same launch gate as supported built-in network applications.

Custom application does not appear

Check:

1. src-phone starts before the application resource.

2. The external resource declares dependency 'src-phone'.

3. config.lua defines PhoneAppConfig and loads before client.lua.

4. registerApp returns true.

5. The ID is valid, unique, and not reserved.

6. Config.Apps is not being used for the custom ID.

7. defaultInstalled matches the expected installation mode.

8. With defaultInstalled: false, open the phone App Store and install the app.

Print the returned registration error code. Do not discard the second return value from registerApp.

Custom application appears outside the phone

Cause: the external resource uses the real application entry as its FiveM ui_page.

The correct fxmanifest.lua uses the transparent page:

ui_page 'web/blank.html'

The real application path remains in config.lua:

uiPage = 'web/dist/index.html',

Also keep the srcPhoneEmbedded=1 guard in web/index.html. Rebuild from web/, then restart the external resource:

cd resources/src-phone-app/web
npm run build

restart src-phone-app

Custom application is blank inside the phone

Check:

• web/dist/index.html exists.

• Vite uses base: './' so built asset URLs are relative.

• uiPage is relative to the resource root, normally web/dist/index.html.

• fxmanifest.lua includes web/dist/index.html and web/dist/**/*.

• The entry-page guard receives srcPhoneEmbedded=1.

• Browser code does not require an unrestricted top frame or popup capability.

Open the client console and look for failed cfx-nui asset requests.

Custom application callback never returns

Check every path in the Lua handler calls cb(...) exactly once:

RegisterNUICallback('records:get', function(data, cb)
    if type(data) ~= 'table' then
        cb({ ok = false, error = 'invalid_request' })
        return
    end

    cb({ ok = true, records = {} })
end)

Also confirm the TypeScript SDK has received its resource name from the shell before calling phone.nui.

Changes are not visible after a web edit

The runtime loads web/dist, not web/src.

cd src-phone/web
npm run build

For an external application:

cd src-phone-app/web
npm run build

Restart the resource that owns the changed bundle. Restarting only src-phone does not rebuild or reload an external resource's top-level NUI.

Information to collect for support

Provide:

• src-phone version.

• Framework and version.

• Voice, garage, keys, fuel, and inventory resources in use.

• Exact start order.

• The first relevant server error.

• The first relevant client F8 error.

• Registration error code for a custom app.

• Whether the issue reproduces with a new character.

Do not provide API keys, database credentials, password hashes, authentication tokens, or full player records.