Troubleshooting

🧰 Troubleshooting

Rivet does not start

Check these first:

1. The server is Paper 1.21.11, not Spigot or an older Paper build.
2. Java reports version 21.
3. There is only one Rivet JAR in plugins/.
4. plugins/Rivet/modules.yml contains true or false for every switch.
5. Every YAML file uses spaces rather than tabs.

The console error usually names the exact configuration file that failed.

A command says its module is disabled

Find the command's module in Configuration, set its switch to true, then restart the server.

/rivet reload notices switch changes but intentionally does not start a disabled module during a live session.

/rivet reload fails

The existing live settings remain active. Read the console for the file path and YAML error, fix that file, then run the command again.

Common YAML mistakes:

• tabs instead of spaces;
• an unquoted : inside a message;
• uneven indentation;
• a missing closing quote;
• a module value such as yes instead of the Boolean true.

A player still lacks a command

Check all three layers:

1. The module is enabled.
2. The player has the command's base permission.
3. The player has any extra target or subcommand permission.

Examples:

• /enderchest needs rivet.inventory.enderchest; targeting Alex also needs rivet.inventory.enderchest.others.
• /kit miner needs both rivet.kit and rivet.kit.miner.
• /rtp world_nether needs both rivet.rtp and rivet.rtp.world.
• /ping Alex needs rivet.ping and rivet.ping.others.

Use /perm check <user> <permission> when using Rivet's built-in permissions.

A configuration change did not apply

• Module switches require a restart.
• Generated files under data/ require a restart after offline edits.
• Most settings/ values apply with /rivet reload.
• Active TPA requests, AFK state and other temporary session records keep their existing state until they end.

A home, warp, spawn or death location is unavailable

The destination world is not loaded or no longer exists. Rivet can load its own tracked test worlds automatically, but it cannot recreate an unrelated missing world.

Restore the world or replace the saved destination.

Random teleport cannot find a location

Check settings/rtp.yml:

• the world is listed under allowed-worlds;
• minimum-radius is not greater than maximum-radius;
• the world border includes the search ring;
• biome allowlists and denylists are not too restrictive;
• maximum-attempts is high enough for the terrain;
• the Nether ceiling limit leaves usable ground.

RTP rejects liquids, dangerous ground and spaces without two blocks of clearance.

/jump, /top or /tree cannot find a destination

These commands deliberately refuse unsafe or obstructed locations.

• /jump needs safe ground and two clear standing blocks near the block in the crosshair.
• /top scans the current column but skips dangerous ground, leaves and blocked standing spaces.
• /tree needs allowed ground plus a clear radius of three blocks and 24 blocks of height.

Check the relevant maximum range in settings/utilities.yml or settings/worlds.yml. Looking at empty space or beyond that range does not create a target.

TPA or spawn teleports keep cancelling

Movement cancellation checks whether the player moved to a different block. Looking around does not cancel it. Walking, falling, knockback or another teleport can cancel the warm-up.

Set cancel-on-move or cancel-on-movement to false, or reduce the warm-up, if that behaviour is not wanted.

A tree does not fell

Tree felling only runs when:

• the player is in Survival;
• the held tool is an axe;
• the broken block is the bottom log;
• the tree has enough logs and natural leaves;
• the structure is not too large or too horizontal;
• no protection plugin cancels any connected block break.

Player-placed persistent leaves are ignored and usually prevent a wooden build from being treated as a tree.

Vein mining does not start

The player must be in Survival and use a pickaxe that can produce a drop from the first ore. Veins larger than the built-in 64-block cap are left alone.

Protection plugins are asked about every block. One denied block stops the whole vein operation.

An Auto Breeder is idle

Confirm that:

• its 9-slot inventory contains at least two correct food items;
• two correct adult animals are within 8 blocks of the breeder;
• the animals are within 8 blocks of each other;
• both animals can currently breed and are not already in love mode;
• the breeder's chunk is loaded.

The machine checks every five seconds, so a short delay is normal.

A grave did not appear

No grave is created when keepInventory is active or when the death produced no drops. The death location is still saved for /back.

If grave saving fails, Rivet leaves the normal death drops in place and writes the error to the console.

Holograms or player glows are missing

Visit the relevant chunk. Rivet recreates saved displays as chunks load.

For permission-limited holograms, check rivet.holograms.view.<lower-case-name>. Run /hologram info <name> to confirm the saved world and coordinates.

For player glows, remove and add the assignment again if needed. Rivet reapplies saved glows when players join. Coloured outlines use the main scoreboard, so another plugin that changes the same player's team may conflict with the colour.

A backpack looks smaller

The visible size comes from default-rows and the player's highest rivet.backpack.rows.<number> permission. Items in hidden rows remain stored in the 54-slot record; they reappear when the player regains enough rows.

/head does not know a player

The player must be online or already present in the server's cached profiles. Rivet does not perform a blocking lookup for completely unknown names.

Where to report a problem

Open a GitHub issue and include:

• Paper version;
• Java version;
• Rivet version;
• the relevant console error;
• the command or action that triggered it;
• the affected settings section with private server details removed.