Skip to main content

Troubleshooting & FAQ

In game​

/traverse says Traverse is not configured, or players get no link. base-url or api-key is still at its placeholder in plugins/Traverse/config.yml, or the web app is unreachable. Fill both in, run /traverse reload, and run /traverse status to confirm the server answers. There is no world id to set any more - the plugin uses whichever world the web app has.

/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: the plugin reaches the server (/traverse status); 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.

/traverse status warns about a version mismatch. The plugin and the web app have drifted apart. The server treats them as compatible only when they share a major.minor version. Update whichever is behind so both are on matching releases.

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 neighbouring-biome 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.

No candidates matched when a neighbouring biome was chosen. Pairing a primary landscape with a specific neighbour is much rarer than the primary alone. The app offers to search again without the neighbour; the 422 NO_CANDIDATES_FOUND response carries canRetryWithoutNeighbour: true. Widening maximumAdjacencyGapBlocks also helps.

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.

Is the service healthy? Hit GET /api/health (no login needed). A 200 means the server and database are up; the body also reports the world state, biome index state, and when the plugin last called in. A 503 means the database is unreachable. See the Plugin API Reference.

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.