> For the complete documentation index, see [llms.txt](https://docs.sourcedev.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sourcedev.pro/src-phone/troubleshooting.md).

# 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](/src-phone/database.md).

## 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:

```lua
ui_page 'web/blank.html'
```

The real application path remains in `config.lua`:

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

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

```powershell
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:

```lua
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`.

```powershell
cd src-phone/web
npm run build
```

For an external application:

```powershell
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.