Troubleshooting

Check that sky_dj started, then read the first server/F8 error. Confirm the effective AdminCommand, ESX group or AdminAce; saved SQL settings may retain a different command.

After an update, install the complete matching runtime, including source/html/index.html and its hashed assets. The UI is already built; customers do not need a frontend toolchain. A mouse cursor alone does not confirm that the page loaded.

Check the assigned job, minimum grade, console distance and routing bucket. Visible controls do not bypass server permissions.

With Config.IngameSettings = true, saved SQL settings override the managed file values. Use the in-game editor or deliberately select file mode in Configuration. Club/device layouts remain in SQL in either mode.

For a revision conflict, reload that section and reapply your edit. For a database error, inspect the first error and stored record before retrying: a timed-out write may already have committed, and that section can remain locked until restart.

Back up sky_dj_state before updates. Do not delete settings, clubs or playlists as an installation fix.

• Check the effective delivery mode/directory, assigned playlist, loaded track and deck-ready state.
• Verify the original .mp3 exists in config/music/, with the exact saved filename. Linux paths are case-sensitive. The catalogue accepts at most 500 files and 50 MiB per file; it does not scan nested folders or symlinks.
• Keep the supplied optional music-pack manifest. Restart the owning resource after adding or replacing music so its pack and catalogue are rebuilt; changing the in-game delivery checkbox alone needs no restart.
• Install matching Lua, server JavaScript and the complete built source/html/ together. A partial update can break the transfer protocol or metadata callbacks even when the mixer opens.
• Check deck faders, crossfader, master and speaker mute/level/range. Stand inside the speaker's listening area and check direction, room boundary and routing bucket.

Both modes need the original MP3 library. Do not delete saved playlists or SQL records to repair missing files. See Installation.

With the supplied manifest and config/music/, neither mode requests the music library automatically during connection. Normal requests the complete optional pack at first local MP3 use, including PFL. Experimental requests only songs currently needed by a deck, preview or audible club.

Test with a fresh-cache client outside a playing club. Spawning inside an audible club can start its music load after joining, which is different from an unconditional connection download.

Check for additional copies in ordinary client files, streamed assets or another resource. Advanced published-folder overrides also cause their own connection downloads. The checkbox cannot remove those copies, cancel an already started Normal pack download or erase FiveM's existing native cache.

A cold Experimental track must finish transferring before duration, seeking and playback become ready. Increasing Experimental MP3: loading …% is progress, even when the total load takes more than 65 seconds. Each accepted block refreshes the playback reporter's inactivity timer; 65 seconds is not a total download limit.

In Normal mode, the first optional-pack download can take longer. The player waits for that mount separately, with a bounded 30-minute observation period, then allows metadata to load. The entire library may be involved, even if only one track was selected.

If progress stalls, inspect the first F8 and server errors. Experimental transfer checks include an opening timeout, a 45-second wait for a pending block and a 60-second idle limit; the playback reporter also rejects a player with no metadata or loading progress for 65 seconds, except while a Normal pack mount is pending. An explicit PLAYER ERROR needs attention; increasing volume does not repair it. Check server load, network delivery and the complete matching resource/frontend update, then try loading the track again.

Experimental sends original MP3 data in 48 KiB blocks, with at most four blocks ahead per transfer. These bounds and the configured per-player/global budgets do not guarantee a download time. Metadata alone starts no audio transfer.

Keep files within 50 MiB each. Experimental cache limit defaults to 128 MiB per player and accepts 64–512 MiB. Loading reserves twice the compressed file size, so a 50 MiB track needs 100 MiB of available budget before playback. Active decoder memory is additional; tracks still used by decks or PFL cannot be evicted.

Unload unused decks and close private previews before retrying a cache-full error. Idle compressed tracks can be evicted; this temporary NUI cache is not a persistent music folder or IndexedDB store. A busy error can occur when the bounded transfer/hash queues are full. Retry after other loads complete; increasing every limit is not proof of multiplayer capacity.

Experimental delivery uses FiveM's latent events. Check whether your server configuration explicitly disabled network-event reassembly, which defaults to true. If it was disabled, restore setr sv_enableNetEventReassembly true so server and clients enable it. This restores the required transport; it is not a speed setting. Keep event limits bounded and check your artifact version if its behaviour differs.

Use /djadmin → Settings → Music & Playlists → Experimental on-demand MP3, confirm when enabling it, and save. With Config.IngameSettings = true, SQL owns this choice; editing the managed value in config.lua does not replace the saved setting. Existing saved choices survive updates, while a fresh installation defaults to Normal.

A successful save switches loaded sources live, cancels stale transfers and requests fresh player metadata. Current tracks may need to load again; preparation or an active automatic transition is reset while tracks and queues are retained. Reload a track if its interrupted request reports cancellation. You do not need another resource, a different music folder or a restart just to switch modes.

Switching to Normal can start its complete optional-pack download as soon as a deck or PFL opens an MP3. Switching back to Experimental cannot undo that download or erase the native cache. Adding or replacing music files remains a separate operation that needs the owning resource restarted. Never reset SQL to change delivery modes.

Start with neutral EQ, reasonable gains and an unclipped source file. Avoid unnecessary overlapping identical speakers; verify tower alignment delays, which deliberately change arrival time.

Compare two clients with the same track: steady playback, entering/leaving range, seek, loop and tempo changes. Note whether Main PA, booth or private PFL is affected. Shared timing cannot guarantee sample-exact playback or repair a corrupt source file.

Trigger one device without music first. If it works but a preset does not, check the FOH's disabled-device counts and restore the relevant family or device to Automatic. Presets intentionally preserve device OFF.

Device OFF and All devices off cancel a manual burst. FOH channel OFF stops its show cues, but a separately triggered test can finish its timed window.

Check a ready playing track, audible deck/mix, enabled sync/channels and device ON/Automatic. Test a rhythmic passage as well as a quiet one.

Normal clubs: use global Settings → Music synchronization. Festival: use the separate FOH → Music Sync page. Save on that FOH page to release festival manual channel ownership; a global settings save does not do this. Individual device opt-outs still remain. See Lights and effects.

Run vantisfxstats in client F8 during an expected burst. This legacy-named, on-demand report shows defined/streamed/visible devices, requested/alive effects, dictionary/model waits, budget waits and native start failures.

Zero requested effects is normal between finite cues. Include the preset, participation counts and whether the single-device test worked; a visible prop alone does not mean emission was requested.

Festival grounds can increase client resmon time and GPU load. Compare the same position with grounds disabled/enabled and effects idle/active. Check FPS too: stable resmon does not establish low GPU cost, and no fixed resmon/FPS value is guaranteed.

Include an in-game measurement and effect diagnostic. Browser previews and mock-native tests cannot prove FiveM visibility or performance.

The menu opens after placement is accepted. Cancelling a new placement should create no device and consume no item. Range is server-wide, with no per-device slider. Spotify Embed is personal playback, not a shared spatial stream. See Boombox.

Install the full updated resource, completely exit FiveM and relaunch. Check for duplicate older copies or another map editing the area. Compare with sky_dj stopped; report terrain/LOD issues separately from audio.