What goes wrong most often, what it actually means, and what to do about it. Most of these come down to load order, the database import, or a setting in config/main.lua.
Installation and Access#
"You don't have permission to use /guitarcreator"
The player lacks the command.guitarcreator ACE. Add add_ace group.admin command.guitarcreator allow to server.cfg, make sure the player is in that group, and restart. The same permission covers /guitarmusic and /guitarprogress, unless you gave them their own in the config.
The cabinets are invisible, or "Model could not be loaded"
guitarpro-assets is not running, or it starts after qs-guitarpro. Ensure the assets first. If you replaced Config.MachineModel with your own prop, check that the prop is streamed and the name is spelled exactly.
The console says "framework: standalone" on an ESX or QBCore server
Your framework started after Guitar Pro, so it was not found. You will notice machines being free and boards showing FiveM names. Move ensure qs-guitarpro below your framework, or force it with Config.Framework = 'esx' (or 'qb').
Players can use /guitarautoplay and the editors
Config.Debug.enabled is still on — it ships on for setup. Set it to false and restart. If autoplay runs were posted, the scores are in guitar_score and can be removed there.
"Missing locale key" warnings in the console
The language you picked is missing some keys that English has, usually after an update added new text. They are shown in English until translated — harmless. Copy the named keys from locales/en.json into your language file to silence them.
Songs and Charts#
The 18 shipped songs say "not generated"
database/sql.sql was never imported, so the shipped charts are not in the database. Import it once and restart, or press Generate on each song in /guitarmusic.
A song is in the music manager but players cannot see it
Players only see songs that have a chart. A song marked not generated needs an admin to press Generate — once it finishes, it appears for players at a machine straight away.
I added an mp3 and it does not show up in /guitarmusic
Restart the resource — the folder is scanned once at boot and new files are only served after a restart. Then check:
It is an mp3, ogg or wav, directly in
songs/or one folder deep (songs/my_song/song.mp3).The name uses letters, numbers,
_and-only. Other names are renamed automatically when the resource stops, so a second restart fixes them.
Analysis fails on a track
The overlay says which step failed:
Message | What to do |
|---|---|
The audio file could not be read | The file is not being served yet. Restart the resource and try again. |
Corrupt or not a supported format | Re-export it as mp3, ogg or wav. |
Too short / silent | The file is empty or nearly so. Check it plays in a normal player. |
No clear beat / tempo could not be tracked / too few usable beats | The track has no steady percussion to lock onto. Ambient, rubato and loose live material will not chart well — pick a song with a firmer beat. |
"Another player is analyzing this song, try again shortly"
Only one person can generate a song at a time. The lock clears when they finish, or after three minutes if they disconnected half way.
Console: "skipped N song(s) that play from the internet"
Those songs were added in an older version from YouTube or a link, which is no longer supported. Their rows stay in guitar_songs but are not offered. To bring a track back, put its audio file in songs/, restart and generate it.
Console: "stored beatmap is invalid, it will be regenerated"
The chart saved for that song could not be read, so the song is treated as not generated. Press Generate on it in /guitarmusic.
The lights and camera cuts are off the beat
The song's BPM is wrong — usually typed by hand. Open it in /guitarmusic and press USE next to the chart tempo to hand the tempo back to the measured one, or type the correct value to two decimals.
Playing#
Notes feel late, or early
Config.Gameplay.audioOffsetMs. It ships at -90; more negative pulls the timing earlier. It applies to the whole server, not per player.
Songs are too hard, or too easy
Config.Beatmap.difficulties sets how dense each chart is and Config.Gameplay.judgments how forgiving the hit windows are. A density change only affects charts generated after it — regenerate the songs you want re-cut. approachTimeMs makes notes travel slower or faster.
Players keep getting booed off stage
Soften Config.Gameplay.life — raise start, lessen miss and bad — or set failEnabled = false to turn failing off entirely.
Duo or Versus is missing, or "not available on this machine"
Both need a two-pad machine, with the mode ticked under Game Modes in the creator — and a second player standing at the other pad.
A run was not saved, or paid no XP
Runs that are quit are never saved. Beyond that, the server rejects a result that does not fit the chart — more notes than it has, a score above its maximum, or a finish well before the song's length — which is what a lag spike or a tampered client produces. With Config.Debug.enabled on, each rejection is printed to the server console. XP and points also need Config.Progression.enabled.
The guitar sits wrong on the character
That prop needs tuning: /guitarplace machine <guitarId> for the cabinet and /guitarplace stage <guitarId> for the venue. The shipped guitars are tuned; base-game props such as the High Roller generally need it.
The time or weather jumps around while performing
Your weather script is not one Guitar Pro knows how to pause. Add its pause and resume events to applyStageTime in client/custom/main.lua, or set Config.Stage.forceNight = false. See Integrations.
A venue I added has no crowd
The camera works anywhere, but the audience is placed per venue. Stand at the venue, run /guitarcrowd, place the spectators and paste the printed block into Config.Stage.crowd.spectators.
Player Messages#
What each message a player can see at a cabinet means. The text comes from the notify section of the locale files.
Message | Means |
|---|---|
This machine is full. | Every pad is taken. |
You are too far from the machine. | The server sees the player away from the cabinet — or, for an arcade cabinet, the player is not in that arcade. |
You do not have enough money to play. | The price is above their cash or bank. In Duo and Versus both players must afford it. |
Wait for the other player to finish their selection. | The other pad is browsing the song list; one at a time. |
The other player is busy right now. | An invite was sent while the other pad is playing or already invited. |
This song is not ready yet. | The song or difficulty has no chart, or was just un-generated by an admin. |
The game session has ended. | The machine was edited, deleted or removed by its arcade while in use, or the player walked away. |
Your partner left the machine. | In Duo the song carries on solo; in Versus the one who stayed wins. |
Still stuck? Open a ticket and include the
[qs-guitarpro]lines from your server console, the F8 console output from the moment it went wrong, and yourserver.cfgload order.



