> For the complete documentation index, see [llms.txt](https://ikcscripts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ikcscripts.gitbook.io/docs/boombox/help/troubleshooting.md).

# 🧰 Troubleshooting

This page covers common installation, interaction, playback, placement, permission, and persistence issues with iKCScripts Boombox.

Before requesting support, check the sections below and review both the **server console** and **client F8 console** for errors.

***

### 📦 Boombox Item Does Nothing

If using the `kc_boombox` inventory item does not start placement, first confirm that the inventory integration selected in `config.lua` matches the inventory system actually running on your server.

#### ox\_inventory

Check that:

* `kc_boombox` is correctly added to your ox\_inventory items
* The item definition is valid
* ox\_inventory is running
* The configured inventory system is set to ox\_inventory
* There are no server or F8 errors when using the item

#### QBCore / qb-inventory

Check that:

* `kc_boombox` exists in `qb-core/shared/items.lua`
* The item is marked as usable
* `qb-core` is running
* `qb-inventory` is running
* The configured inventory system matches your QBCore setup
* The server was restarted after adding the shared item

{% hint style="info" %}
Changes to `qb-core/shared/items.lua` may require a server restart before the new item is available correctly.
{% endhint %}

#### ESX

Check that:

* The provided `items.sql` was imported
* `kc_boombox` exists in the required database items table
* `es_extended` is running
* The configured inventory system is set for ESX
* There are no errors when the usable item is registered

***

### 🎯 No Interaction Appears

If the Boombox is placed but no Open or Pickup interaction appears, check the interaction system selected in `config.lua`.

#### ox\_lib TextUI

Make sure:

* ox\_lib is running
* You are standing within interaction distance
* The placed Boombox exists
* Another resource is not repeatedly hiding or replacing the active TextUI

The owner should see:

```
[E] Open Boombox • [G] Pick Up
```

Other nearby citizens should see:

```
[E] Open Boombox
```

#### ox\_target

Make sure:

* ox\_target is running
* Boombox is configured to use ox\_target
* The placed Boombox has finished networking
* You are within the configured target distance

#### qb-target

Make sure:

* qb-target is running
* Boombox is configured to use qb-target
* The placed Boombox has finished networking
* You are within the configured target distance

{% hint style="info" %}
Target interactions are registered against the exact networked Boombox entity. Immediately after placement or restoration, the entity may require a brief moment to become available to the client.
{% endhint %}

***

### 📍 Placement Does Not Start

If using the inventory item does not enter Placement Mode, check:

* The correct inventory integration is configured
* The `kc_boombox` item is registered correctly
* The character is not in a state that prevents placement
* The Boombox prop model can load
* ox\_lib is running
* There are no F8 errors
* There are no server console errors

Also verify that the inventory item is actually reaching the Boombox usable-item handler.

***

### 👻 Placement Preview Does Not Appear

If Placement Mode starts but the Boombox preview does not appear, check the client F8 console for model-loading or script errors.

Boombox uses:

```
prop_boombox_01
```

for the physical Boombox.

Make sure another resource is not interfering with or removing the model.

***

### 📋 Placement Instructions Disappear

The placement instructions should remain visible while Placement Mode is active until placement is confirmed or canceled.

If they disappear unexpectedly:

* Check the F8 console for errors
* Confirm ox\_lib is running correctly
* Check whether another resource is repeatedly using or hiding ox\_lib TextUI
* Restart `kc_boombox` and test again

***

### ❌ Boombox Will Not Place

The server validates placement before creating the real Boombox.

Placement can be rejected if:

* The requested position is invalid
* The position is outside the configured placement distance
* The character is in a state where placement is not permitted
* Required entity/network conditions are unavailable
* Server-side validation fails

If placement fails, the inventory item should not be consumed.

{% hint style="warning" %}
Do not manually remove the item from a citizen's inventory while troubleshooting placement. The resource handles item removal only after successful placement.
{% endhint %}

***

### 📦 Cannot Pick Up the Boombox

Only the **owner** can pick up a placed Boombox.

Check that:

* You are the original owner
* You are close enough to the Boombox
* The exact Boombox entity is available
* Your configured interaction system is working
* There are no server validation errors

You do **not** need to open the Boombox interface before picking it up.

Trusted Friends and citizens using Others Around cannot pick up another owner's Boombox.

***

### 🎵 Music Does Not Play

If the interface works but music does not play, check:

* xSound is running
* The URL is supported
* The URL is still available
* The content is publicly accessible
* Boombox volume is above zero
* You are within the configured audio distance
* There are no F8 or server errors

Try another known-supported URL.

{% hint style="info" %}
If other supported URLs work correctly, the issue is likely related to the individual URL or external provider rather than the Boombox installation.
{% endhint %}

***

### 🟢 Spotify URL Does Not Play

Spotify page URLs are not supported as direct playback sources.

Use a supported YouTube URL or compatible direct-audio URL instead.

See:

→ **🔗** [**Supported URLs**](/docs/boombox/help/supported-urls.md)

***

### 🔊 Music Is Too Quiet or Too Loud

Check:

```lua
Config.DefaultVolume
Config.MaxVolume
```

The standard maximum volume is:

```lua
Config.MaxVolume = 0.75
```

Also check the current volume selected inside the Boombox interface.

Remember that positional audio becomes quieter as you move farther away from the physical Boombox.

***

### 🔇 Music Stops When Moving Away

This is normal positional-audio behavior.

The Boombox has a configured listening distance:

```lua
Config.AudioDistance
```

Music fades as the listener moves farther away and becomes inaudible outside the configured range.

***

### ⌨️ PAGE UP / PAGE DOWN Does Nothing

Volume keybinds require a valid selected Boombox.

Check that:

* You previously opened the specific Boombox
* The Boombox still exists
* You are within the required control distance
* You have permission to control it

Default keys are:

```
PAGE UP     Volume Up
PAGE DOWN   Volume Down
```

The keybinds intentionally do not select the nearest Boombox automatically.

***

### 👥 Other Citizens Cannot Control the Boombox

Normal nearby citizens require:

```
Others Around = ON
```

They must also remain within the configured control distance.

Check:

* Others Around is enabled
* The citizen is close enough
* They are controlling the correct Boombox
* The server is accepting their permission state

Alternatively, add the citizen as a **Trusted Friend** if you want them to retain access while Others Around is disabled.

***

### 👥 Trusted Friend Cannot Control

Check that:

* The friend was successfully added
* They are still listed under Trusted Friends
* They are within the configured control distance
* They are interacting with the correct Boombox
* The Boombox belongs to the citizen who added them

Trusted Friend access does not provide unlimited remote control.

See:

→ **👥** [**Trusted Friends**](/docs/boombox/features/trusted-friends.md)

***

### 🔒 Citizen Can Open but Cannot Control

This can be normal.

A citizen may have **View Only** access when they are not:

* The owner
* A Trusted Friend
* Authorized through Others Around

Opening the interface does not automatically provide playback-control permission.

***

### 📋 Queue Is Not Updating Correctly

If Queue actions do not behave correctly:

* Confirm you have permission to control the Boombox
* Confirm you are within control distance
* Make sure you are controlling the exact Boombox you opened
* Close and reopen the interface
* Check the F8 console
* Check the server console

Queue changes are validated by the server before the authoritative Queue is updated.

***

### 🎶 Playlist Problems

If Playlists are not saving or loading correctly:

* Check the server console for data-write errors
* Confirm the resource data directory is writable
* Confirm the citizen has a valid persistent identifier
* Restart `kc_boombox` and test again

Do not delete playlist data while troubleshooting unless you intentionally want to reset stored Playlists.

See:

→ **🎶** [**Playlists**](/docs/boombox/features/playlists.md)

***

### 🕘 History Is Not Saving

History is stored persistently by the server.

If History disappears after reconnecting or restarting:

* Check the server console for file-write errors
* Confirm the resource data directory is writable
* Confirm the server can identify the citizen persistently
* Make sure the data files have not been manually reset or deleted

***

### 💾 Boombox Missing After Restart

Placed Boomboxes are stored persistently.

If a saved Boombox does not immediately appear after a restart, first allow the server and nearby clients time to establish the required game/network conditions.

Check:

* OneSync is available
* The saved Boombox data still exists
* The resource data directory is readable
* `kc_boombox` started successfully
* There are no persistence errors in the server console
* A citizen is eventually near the saved Boombox location

{% hint style="info" %}
Persisted Boombox restoration may be deferred until suitable game/network conditions are available rather than forcing creation before the entity can be networked correctly.
{% endhint %}

***

### ♻️ Duplicate Boomboxes After Restart

Do not manually create additional persistence entries.

If duplicate physical props appear:

1. Stop `kc_boombox`.
2. Review the server console for restoration errors.
3. Check the saved Boombox data before deleting anything.
4. Restart the resource and test again.

{% hint style="warning" %}
Do not delete live persistence data as your first troubleshooting step. Existing records may represent legitimate citizen-owned Boomboxes.
{% endhint %}

***

### 💾 Data File Write Errors

If the server reports that a Boombox data file could not be written, check the file and folder permissions for the resource.

The server process must have permission to write to the Boombox data directory.

This can affect:

* Placed Boombox persistence
* History
* Playlists
* Trusted Friends
* Stored preferences

{% hint style="warning" %}
Back up existing data before manually modifying permissions, replacing files, or resetting persistent storage.
{% endhint %}

***

### 🖥️ Interface Is Grey, Blank, or Does Not Open

Check:

* The client F8 console
* The server console
* That all Boombox web/NUI files are present
* That the resource was installed completely
* That no files were accidentally removed or renamed

Then restart:

```
kc_boombox
```

and test again.

***

### ⌨️ Ctrl + V Causes Character Actions

While the Boombox interface has focus, gameplay controls should be prevented from triggering character actions.

If pressing Ctrl + V causes fighting, attacking, or other gameplay behavior:

* Check the F8 console
* Confirm you are using the current Boombox files
* Restart `kc_boombox`
* Check whether another resource is interfering with NUI focus or control states

***

### 🎯 Wrong Boombox Is Being Controlled

The resource is designed to control the **exact Boombox that was selected**.

It should not automatically switch to the nearest Boombox.

If you believe the wrong Boombox is being controlled:

* Close the interface
* Interact directly with the intended Boombox
* Test again
* Check F8 and server console errors

If the selected Boombox is deleted or picked up, its selection should be cleared.

***

### 🔄 After Changing Configuration

After editing:

```
config.lua
```

restart:

```
kc_boombox
```

For framework, inventory, or shared-item changes, a full server restart may be preferable.

***

### 🆘 Still Need Help?

If the problem continues, collect:

* **Resource:** kc\_boombox
* **Framework:** Qbox, QBCore, ESX, or other
* **Inventory:** ox\_inventory, qb-inventory, ESX inventory, or other
* **Interaction:** ox\_lib TextUI, ox\_target, or qb-target
* **Server Error:** Complete console error
* **Client Error:** Complete F8 error
* **Steps:** What you were doing when the problem occurred
* **Media:** Screenshot or short video when useful

{% hint style="success" %}
Providing the exact error and steps needed to reproduce the problem makes troubleshooting significantly faster.
{% endhint %}

Continue to:

→ **💬** [**Support**](/docs/boombox/help/support.md)