Skip to content

Troubleshooting

Organised by what you are seeing, in the words you would use. If your symptom is not here, the exact text of the message usually is — search the page for a phrase from it.

“Nothing happened when I installed it”

Section titled ““Nothing happened when I installed it””

The release zip extracts into your server’s Resources folder, and the server has to be restarted afterwards. Install on your server lists what should end up on disk, including the folder people forget. If the paths are right and the server still starts without BeamJoy, the server’s own console log says why on startup.

“It says this mod is not compatible with any other BeamJoy version”

Section titled ““It says this mod is not compatible with any other BeamJoy version””

It is not. An older BeamJoy, or BeamJoy Free, left in Resources has to be removed before this one will run. Two versions in the same server do not coexist.

“I can’t change anything — I have no permissions”

Section titled ““I can’t change anything — I have no permissions””

Nobody is the owner yet. Ownership is claimed once, from the server console, by name:

Terminal window
bj group YourPlayerName owner

The welcome window on a fresh install shows this command with a copy button. First boot and ownership is the whole step.

The action you tried belongs to a group above yours. Which action needs which group is Groups and permissions — and an owner can move any of them.

That is BeamJoy telling you so, with the build numbers beside it:

Your BeamJoy UI looks out of date. Close BeamNG completely, clear your cache, then relaunch.

The game’s interface layer caches its own copy of BeamJoy’s UI and can keep serving a stale one after the server updates. The fix is exactly what it says, and the order matters — close the game fully first, then clear the cache, then start it again. Restarting without closing BeamNG completely is the usual reason it comes back.

If it shows for every player after you updated the server, the server-side build and the UI build genuinely differ; that is a packaging problem on the server, not something players can clear.

“Buttons do nothing, or the window is behaving oddly”

Section titled ““Buttons do nothing, or the window is behaving oddly””

Same cause, same fix as above: a stale cached UI against a newer server. Close BeamNG, clear the cache, relaunch.

That is deliberate. Two things keep it open:

  • ForceHud, which is on by default and keeps the window open for everyone. It is in Config → General.
  • Being staff. Staff always keep the window, regardless of ForceHud.

So on a default install nobody can close it until an owner turns ForceHud off.

BeamJoy ships English plus thirteen translations and follows the game’s language. A language the game itself ships no pack for — Italian among them — needs a community language pack installed in BeamNG before anything can display in it.

Players’ mods are client-side only on a BeamJoy server, and the server’s own served mods cannot be disabled or removed by a player. A vehicle mod the server does not allow is disabled automatically when it is downloaded.

“My time didn’t go on the leaderboard”

Section titled ““My time didn’t go on the leaderboard””

Four reasons, in order of how often they are the one:

  1. An anticheat option was off. The start panel warns before you go: “One or more anticheat options are disabled for this attempt. Your time will not be counted on the leaderboard. Start anyway?” All three anticheat switches are on by default; a host turned one off.
  2. The lap went through the pit lane. A lap that touched the lane counts for race time but never for best lap or the leaderboard, so a drive-through can never be a shortcut.
  3. The race was saved after you set it. Saving a race in the editor deletes every recorded time for it, because the gates may have moved underneath them.
  4. You were running it passively. Passive runs are timed on the race’s own Passive board, which is a different board from the grid one.

A passive run is a clean single lap, and BeamJoy says which rule ended it: you reset the car, changed car, were moved or teleported, used the node grabber, changed gravity, slowed or paused the game, or went too long without reaching a gate. Any one of those ends the run with no time.

The grid is waiting on somebody. In a lobby with Multiplayer on, the countdown waits for everyone to ready up, and it cannot start before the grid ready timeout has elapsed at all — ten seconds by default, which is there to give latecomers a chance. The grid timeout is the hard cutoff: 180 seconds by default, after which ready racers start and anyone not ready is dropped.

The number of start positions is the maximum field size, and a race with only one start position is forced solo — BeamJoy turns Multiplayer off on save, so the toggle will not stay on. Add grid slots in the race editor.

Two race rules can refuse a reset:

  • The reset speed limit, which only allows a reset below a set speed so it cannot be used as an airbrake. The HUD says “Too fast to reset! Below {limit} km/h only”.
  • The respawn strategy, which can be No respawn outright.

Racing has both, with their defaults.

“I was marked DNF and I was still driving”

Section titled ““I was marked DNF and I was still driving””

DNF on stall watches for progress, not movement — a car going round in a field is not getting to the next gate. The warning shows in the last few seconds: “Not moving! DNF in {seconds}s, keep going!” The timeout is 30 seconds by default and the host can raise it or turn the rule off.

“I crashed out of the server mid-race”

Section titled ““I crashed out of the server mid-race””

Rejoin. A disconnected racer has a window to come back and carry on from their last checkpoint, in their exact car — ten minutes by default. The clock keeps running while you are gone, and a server can set it to 0, which retires you immediately.

“There’s no Races tab in the config window”

Section titled ““There’s no Races tab in the config window””

Editing races needs the EditRaces permission, which is mod and above by default.

Races belong to the map they were built on. A different map shows a different list — nothing is lost. If you are on the right map and still cannot see it, the server may have Only show editable races on, which hides races you are not allowed to manage.

Either the server has Restrict editing to authors on and this is not your race — “You can only edit or delete races you created” — or the save is being refused for one of the hard rules:

  • a name under 3 or over 40 characters, or one another race on this map already uses;
  • fewer than 2 gates;
  • no start position at all.

The Save button is also simply greyed out until something has actually changed.

“The Pits section is greyed out, or pits stay off”

Section titled ““The Pits section is greyed out, or pits stay off””

The Pits section itself only appears once the race is Loopable, and the pits stay unusable until six things are true. The section names the missing one each time — the full list, in the order it checks them, is in the race editor.

“I reversed the route and the grid is facing the wrong way”

Section titled ““I reversed the route and the grid is facing the wrong way””

Expected. Reverse flips the gate order and turns every gate, but start positions are not moved. Rebuild the grid after reversing.

“Importing the map’s races skipped most of them”

Section titled ““Importing the map’s races skipped most of them””

Each row says why. Name already used is the common one — importing never overwrites a race you already have, so it is always safe to re-run. Can’t be read means the map’s own race data is not convertible.

“Legacy import overwrote my hunter arena”

Section titled ““Legacy import overwrote my hunter arena””

Hunter arenas import one per map and overwrite an existing arena for that map; the preview flags this before you confirm. Races never overwrite: every convertible race is added as a new one, and a name collision is skipped instead.

Traffic ships off. It is turned on in the config window, and it is also permissioned, so a player may be able to see the control without being allowed to use it.

There is no webhook configured. Discord integration does nothing until a webhook URL exists, and because a webhook URL lets anyone post to that channel, only holders of the config permission can see or set them.

The messages are specific, so take them literally:

It says What it means
Couldn’t reach GitHub to look for a BeamJoy release The server machine has no outbound internet, or GitHub is blocked.
its release has no BeamJoy-Revived-<version>.zip to install The release exists but the asset does not. Download and install it by hand.
couldn’t be unpacked / BJ.zip couldn’t be built Downloaded fine, failed to assemble. Nothing was changed.
<tool> wasn’t found on the server machine The updater needs curl and, on Linux, unzip and zip; on Windows it uses PowerShell. The message names the one that is missing and how to install it.
Restart the server to start using it It installed. It is not live until the server restarts, and players should clear their cache before rejoining.

The previous version is saved to a backup folder, which the success message names.

Map votes and kick votes both need a share of eligible voters — 51% by default — inside a timeout, 30 seconds by default. On a quiet server the threshold is the thing that is failing, not the vote.

  • The server console log is the first place to look for anything that happened at startup or during a save. BeamJoy writes its reasons there in plain language.
  • The game’s own log holds the client side, including which BeamJoy build the client actually loaded — which is the server’s copy, not whatever is in the player’s own mods folder.
  • The Discord linked from the project’s GitHub is where to ask, and the issue tracker is where a reproducible bug should end up.