TROUBLESHOOTING & FAQ

The server won't start

Fabric says a mod is missing or incompatible. Read the list it prints, it's usually right:

  • Fabric API missing: put it in mods/. With Strapped it has to be 0.165.2 or newer.
  • Minecraft version wrong: the Soulverse file is for one game version. Get the one for yours from Modrinth (26.3, 26.2 or 26.1.2).
  • Java too old: Soulverse needs Java 25. Check with java -version on the server, or pick Java 25 in your host's panel.
  • fabricloader too old: update Fabric Loader to 0.19.5 or newer.

"Strapped" is refused at startup. Soulverse needs Strapped 0.2.0-beta or newer. Update it, or take it out (Soulverse works without it). Strapped also can't run next to the original Accessories mod.

It crashes with a long error. Check logs/latest.log (or the crash report) for the first mod named in it. If it's Soulverse, report it on Modrinth with the log.

Players can't join

"Missing" or "registry" errors when joining. The player doesn't have Soulverse, or doesn't have one of your server's other content mods. Everyone needs the same mods that add things (Soulverse, Strapped, Kaleidoscope, and so on).

They have Soulverse, but get kicked on join with something about a packet or payload. Their version doesn't match the server's. Soulverse doesn't check versions for you, so make sure everyone has exactly the same file. A modpack is the easy way.

"Freecam isn't allowed on this server." You have Kick Freecam users on and their game has a Freecam mod. They can remove it or switch to Freecam (Fair Play). Staff can be given soulverse.freecam.allowed.

The menu

Everything in /sv is greyed out. It's permissions. Ops have everything; with LuckPerms check what they have with /lp user <name> permission check soulverse.server.view. Remember a Server tab setting needs both soulverse.server.view and its category. See Permissions.

I edited soulverse-server.json and nothing changed. Run /sv reload. Hand edits only apply on reload or restart.

There's an orange "Restart required" line. You changed something that only takes effect after a restart: Additional Souls, or another mod's config file in Mod Configs. Restart the server. In singleplayer, leaving and re-joining the world is enough for Additional Souls; another mod's settings need the game restarted.

I switched on Additional Souls, restarted, and the SOULs aren't there. Check the switch is still on (Server tab, Expansions) and that the server actually restarted rather than reloading. /reload isn't a restart.

A player I'm looking for isn't in the list. The Players tab lists everyone who ever joined. Try their Minecraft username, not their character name, or the other way round.

Lives and ghosts

Players don't lose lives when they die. That's the default: only another player takes a Human's life. Turn off Humans: only PvP costs a life if you want every death to count.

Monsters never lose lives. Monsters have none unless Monsters have lives is on.

Nobody becomes a ghost. Either lives are off, or Ghost Mode is off (then they go to plain spectator mode).

I made a new world and everyone kept their old SOUL and lives. Players' files are in config/soulverse/, not in the world, so they carry over. For a fresh start move the old <username>.json files and logs/ out of the folder before the new world first starts. See First start & files.

I restored a backup and players' characters are wrong. You restored the world without its matching config/soulverse/. Always back up and restore the two together.

Other mods

Chat looks wrong with my chat plugin or mod. Turn on Vanilla chat formatting (Names category). Chat then goes back to <name> message.

Players see usernames, not character names (or the other way round). That's Show chosen names in the Names category.

Voice chat buttons are greyed out. Simple Voice Chat isn't on the server, or its own voice server didn't start. Check its port (UDP 24454 by default) is open.

Maps still show caves. Xaero's gets the rules two seconds after joining, so reconnect once after changing them. Xaero's can only turn caves and radar off together. Players using a map mod that isn't Diorama, Xaero's or JourneyMap aren't covered.

Questions

Does Soulverse go on the server, the clients or both? Both, the same version on every side.

Can I run it without the client mod, server-side only? No. Players need it to join.

Do I need LuckPerms? No. Without it, ops can do everything and players can't. LuckPerms is for when you want helpers or moderators who aren't ops.

Can I turn off one quirk? Yes, every quirk has its own switch on the Quirks tab, plus its numbers. All Quirk Waits and All Quirk Damage scale them all at once.

Can I stop people picking a SOUL? Yes, on the SOULs tab: grey it out, hide it, or disable it (people who have it then choose again).

Can I give someone a different SOUL? Their page in the menu, or /sv players soul <player> <soul>. /sv players prompt_soul <player> asks them to choose again themselves.

Is it safe to remove Soulverse later? The world will load without it, but Soulverse's items and blocks go missing and characters only live in config/soulverse/. Back up first.