Skip to main content

Troubleshooting & FAQ

In game​

/traverse says Traverse is not configured for this server. active-world-id is blank or still CHANGE_ME in plugins/Traverse/config.yml. Copy the world id from the admin console and run /traverse reload.

/traverse says the player has no active entitlement. They did not qualify. Check the world's qualification mode and values against the player's actual LuckPerms groups or permission nodes. In GROUP mode the values are group names; in PERMISSION mode they are node names, and the node must match exactly. Operators always qualify, which makes them a poor test of whether the rule itself is right.

Nothing happens on join, and no dialog appears. Check, in order: active-world-id is set; the world is ACTIVE rather than scheduled, ended, or disabled; the player qualifies; the world has both dialogTitle and dialogMessage set, since the dialog is skipped if either is missing; and the player has not already been shown it once.

The plugin will not load. Confirm the server is Paper 1.21.7 or newer on Java 21. The onboarding dialog uses Paper's Dialog API, which does not exist on older builds, and the plugin does not run on Spigot or CraftBukkit.

Group-based qualification never matches. LuckPerms is a soft dependency. Without it installed, no groups can be resolved and only operators and direct permission holders qualify.

The player gets a link but it fails to open the app. Compare the plugin's base-url with the server's PUBLIC_BASE_URL. Links are built from the server's value, so if the two disagree the plugin may be reporting a host the player cannot reach.

"This link has expired." Access links live 15 minutes. Run /traverse for a new one.

"This link has already been used." Links are single use. Run /traverse again. If a supporter reports this without having clicked the link, treat it seriously: someone else opened it.

"This link is invalid." The token does not exist. Usually a truncated or mangled copy and paste. Issue a fresh one.

The supporter cannot get a link at all. Grant access by hand from the admin console using their Minecraft username. That issues a code directly, bypassing the plugin and the qualification check.

The search returns no candidates. See How Matching Works for the full list. The usual causes are a landscape that does not occur in the search band, thresholds set too tight, a two-selector request that is too specific, or a world with little space left.

The search returns a 503 about an unsupported Minecraft version. The world's minecraftVersion is outside what the biome engine can generate. Set it to a supported value; see Installation.

The search returns an unknown biome selector error. A biome category contains a name the engine does not recognise for that version. Check the category's members against the version the world is set to.

A supporter wants a different set of candidates. Candidates are generated once per supporter and re-running the search returns the same set rather than rerolling. Handle this as a staff action.

Previews look nothing like the live server. Biomes come from the seed, not the live world. Confirm the seed and version match the running server, and remember that terraforming and player builds are invisible to the engine.

Web app​

The server refuses to start, complaining about SESSION_SECRET. It must be at least 32 bytes. Generate one with node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".

The server refuses to start, complaining about PUBLIC_BASE_URL. It is required. Set it to the app's public root, including the scheme.

Admins are signed out immediately, especially on Safari or iOS. Cookies are marked secure based on PUBLIC_BASE_URL's scheme, and browsers drop secure cookies on plain HTTP. Serve over HTTPS in production and set the variable to the https:// URL.

The build fails on the native addon. The biome engine compiles Cubiomes from source. Confirm the submodule was fetched with git submodule update --init --recursive, and that a C/C++ compiler, Python 3, and node-gyp are present. On Windows that means Visual Studio Build Tools with the "Desktop development with C++" workload; gcc and MinGW are not the supported path.

The world map is blank or stale. Rebuild the biome index from the admin console and wait for it to report ready.

Claims​

A supporter revealed the wrong place. There is no undo in the app by design; the reveal is the deliberate, single choice the whole flow is built around. Staff can release the claim from the admin console, which frees the area and lets a fresh entitlement be granted.

A claim should stay on record but stop blocking others. Turn off exclusion on that claim rather than releasing it. The claim stays; the area stops being reserved.

Two supporters ended up close together. Check minimumSelectionGap. It applies at search time, so claims granted before it was raised are unaffected.