Documentation
Fixes for the most common Waypoint problems on FiveM: nothing drawn, no route arrows, markers not visible from far, the edge indicator, lost styles, keybinds and style codes that will not import.
What goes wrong most often, what it actually means, and what to do about it. Most of these are a setting doing exactly what it was told — the waypointdebug command and the F8 console usually say which.
Check, in this order:
The resource is started: ensure qs-waypoint in server.cfg, and the folder is still called qs-waypoint.
The player has not switched it off: /waypoint → General → Waypoint marker. The preview then reads Waypoint disabled.
Config.OnlyInVehicles is true and the player is on foot.
The profile's Visibility hides it: Hide when closer than is larger than the distance, or Maximum distance is smaller.
The F8 console shows [qs-waypoint] the icon page did not load — see the next entry.
The icon is a small page inside the resource, and the game could not open it within ten seconds of starting. Almost always the web/build folder is missing or incomplete — a partial upload over FTP, or files removed by an antivirus. Download the resource again from the CFX Portal and replace the whole folder. The world marker, ring and beam still work in the meantime; only the icon and the edge indicator are missing.
Either Config.Command is empty or set to another word, or another resource registers /waypoint too and wins. Change Config.Command to a word nothing else uses, such as "wpcreator", and restart the resource.
Correct behaviour. FiveM stores each player's key bindings, and the config value is only the starting key for players who have never had the binding. Players who already have it change it themselves under Settings → Key Bindings → FiveM → Waypoint creator.
Correct behaviour. Config.DefaultStyle is only the starting point. Players who already joined have their profiles saved on their own computer, and those are never overwritten from the server. The new style reaches new players, new profiles, and anyone who presses Reset. To hand an existing community a new look, export it from the creator and share the code.
Styles are stored on each player's computer under the resource's name. They are lost when:
The resource folder was renamed. Rename it back to qs-waypoint and the styles return.
The player joined from another computer, or cleared their FiveM cache and data.
Config.MaxProfiles was lowered — profiles above the new limit are dropped.
Show the route is off in the active profile.
The destination is closer than 40 m, or further than 4 km (3 km in performance mode). The arrows appear on their own once inside that window.
There is no road to follow: the player is off-road, on water, inside an interior or in the air. The route walks the road network and starts from the nearest road.
Trail length is very short, or Trail opacity very low.
Run waypointdebug: it prints the distance, whether the route is on, and how many road points it found.
The trail is built step by step along the roads, always taking the next road point that gets closer — a street guide, not a full sat-nav. At a large interchange it can pick a longer way or stop early, and it rebuilds as the player drives, so it corrects itself within a few seconds. If it happens often, set Config.PerformanceMode = false: the accurate preset asks the game for real driving distances at junctions and picks far better turnings.
On purpose. Where the ground found above the road is a bridge deck, a roof or a tunnel ceiling rather than the road itself, the arrow is left out rather than drawn floating in the wrong place. The trail resumes on the other side. waypointdebug counts these as dropped, off the ground line.
There is one trail at a time, and the map waypoint comes first. The job's point is still drawn with its icon and marker. To route to it, the player clears their map waypoint — or the job sets the map waypoint itself with SetNewWaypoint, as described in Integrations.
A limit of the game, not of the script: GTA only draws 3D markers within a few hundred metres, whatever their size. From further out the icon shows the way. For something visible over the city, turn on the Light beam and raise its height.
Show at the screen edge is off in the profile, or the destination is just past the edge of the screen. The indicator appears once the destination is more than 45° from where the camera is looking, so turning a little further brings it in.
Correct behaviour. Every waypoint uses the icon of the player's active profile; AddWaypoint can change its colour, size and everything else, but not the drawing itself. Use colour to tell points apart.
Points added with AddWaypoint stay until the script that added them calls RemoveWaypoint with the same id — arriving does not remove them. Check that the script removes its point on arrival and on cancel. A player stuck with one is freed by reconnecting.
The code was cut short when copied, or picked up extra text around it. Copy it again in full — clicking the Export box selects all of it — and paste it on its own. Codes start with QSWP1:; codes from other scripts are not compatible.
The player is at the profile limit — the Share window says Profile limit reached. Delete a profile, or raise Config.MaxProfiles, and import again.
Still stuck? Open a ticket and include the output of
waypointdebug, any[qs-waypoint]lines from the F8 console, yourconfig.lua, and the steps that reproduce the problem.
