Troubleshooting#

Each entry below is a failure mode that has a specific cause in the mod's own code path. Start from the server log: VSU logs under the logger name vonix_server_utilities and prefixes most lines with [VonixSU].

Database will not initialise#

Symptom. The log shows Database initialisation failed with a stack trace, and every persistent command fails. /home reports a home not found rather than an error, because the lookup returns null on a failed query.

Causes and fixes.

A restore that copies data.db but leaves an old data.db-wal in place will either fail to open or read inconsistent data. Always remove both sidecars when replacing the database.

Players are locked out of every command#

Symptom. Non-op players, and sometimes operators too, get "unknown command" or a permission failure for every VSU command right after installing LuckPerms.

Cause. This is the 1.6.0 behaviour, where LuckPerms was authoritative and an ungranted node read as a denial. It is not how 2.2.0 works: the gate is a union of the LuckPerms grant and the operator level, so an unconfigured LP install still lets every op-0 command run and keeps operators working.

Check first. Confirm the jar is actually 2.2.0:

/vonixsu version

The version line prints the embedded version. If it reports anything below 1.6.1, replace the jar.

If you are stuck on an old build, grant a namespace wildcard on the affected groups as a temporary measure, then move to explicit nodes. Details are on Permissions.

If 2.2.0 still denies a player, the player is not op and the command's fallback is above 0. Grant the node. /hat works for everyone; /more needs either op 2 or the node.

kits.json parse errors#

Symptom. /kits lists only starter, tools, and food after you added your own kit, or the log shows kits.json: root is not an object — using defaults.

Cause. The file failed to parse or its shape is wrong, so the kit manager fell back to the hard-coded defaults. It does not keep a partial load.

Fix. Validate the JSON, confirm the root is an object with a kits array, and run /kit reload. The reload message reports how many kits loaded:

Reloaded kits.json — 7 kits loaded.

A count of 3 after adding kits means the file is still being rejected.

A malformed group never causes a failure. A missing, blank, numeric, or object-valued group falls back to the kit name. If two kits unexpectedly share or do not share a cooldown, check the group values first.

Unknown item ids in kits#

Symptom. A kit claims successfully but is missing items.

Cause. Item ids are validated against the item registry when the file loads. An id that does not exist on your modpack — for example a modded item you uninstalled, or a typo such as minecraft:iron_pickaxe with a trailing space — is dropped with a warning, and the rest of the kit still loads.

Fix. Watch for the references unknown item warning at load, correct the id, reload. Use the exact namespaced form from the creative menu or /give completion. Note that the check happens at load time, so an item registered by a mod loaded later in the startup order can be rejected if kits load first.

Mutes that appear to do nothing#

Symptom. /mute Steve reports success, the row exists in punishments, but Steve keeps talking.

Causes, in order of likelihood.

1. Steve holds vsu.bypass.mute. The bypass is checked at enforcement time and is invisible in the command output. Check the node: lp user Steve permission check vsu.bypass.mute
2. The mute was issued to the wrong identity. Mutes key on UUID. A name change means the row is against the old UUID; /banlist shows the stored name. /mute resolves online players and profile-cache names, so muting the current name of an online player is correct — but a historical name may point elsewhere.
3. A plugin or another mod is handling chat ahead of VSU. VSU cancels the loader chat event. If a chat plugin intercepts earlier and broadcasts anyway, the cancel has no effect.
4. The server has just started. Until mute hydration completes, the check fails closed — which is the opposite of this symptom — so a just-started server should block chat, not allow it. If chat is allowed immediately after boot, check for an error in the hydration log line.

Confirm the enforcement path. Have the muted player send one chat message. A working mute produces You are muted with the remaining time and the reason. No message means VSU's hook is not seeing the event.

Expired punishments still applying#

Symptom. A tempban or tempmute past its expiry is still in force.

Cause. Expiry is applied by the sweeper, which runs every 60 seconds. A row that expired seconds ago is still active=1.

Check.

SELECT id, type, target_name,
       datetime(expires_at/1000,'unixepoch') AS expired_at, active
  FROM punishments
 WHERE active = 1 AND expires_at IS NOT NULL
   AND expires_at <= (strftime('%s','now')*1000);

Rows returned here should disappear within a minute. If they persist, the sweeper is not running — look for ExpirySweeper started (60s cadence) at startup and any ExpirySweeper tick failed warnings after it.

Mutes are the visible case, because the in-memory set is only reconciled by a sweep or an unban. A ban is re-checked from the database at login, so an expired ban stops blocking as soon as its expires_at passes, regardless of the sweeper.

Permission denied for a non-op player#

Symptom. A player cannot run a command that other players can.

Cause. Almost always a missing node on their group, and specifically for a command whose fallback is above 0. Verify what they hold:

lp user Steve permission check vsu.command.home
lp user Steve permission check vsu.command.utility

Empty output from permission check means the node is not granted and no parent grants it. Wildcards only help if they were granted at a parent level.

Two commands surprise people because of their fallback rather than their name:

• /more, /clear, /repair, and /anvil all need op 2 or the node.
• /enderchest needs vsu.admin.peek at op 2 in both its self and target forms.

Also check that the player is not muted. The chat-style commands are cancelled by the moderation hook, which reports as a mute message rather than a permission error. If the failure message mentions being muted, the cause is a punishment, not a node.

Reload does not apply kit changes#

Symptom. You edited kits.json, ran /vonixsu reload, and /kits is unchanged.

Causes and fixes.

Note that /kit reload and /vonixsu reload are different commands. /kit reload re-reads only kits.json; /vonixsu reload re-reads the properties file and then the kits file.

Jar or loader mismatch#

Symptom. The server refuses to start, or the mod is absent from the mod list.

Cause. The jar was built for a different Minecraft version or a different loader. A Forge jar does not load on NeoForge and vice versa, even on the same Minecraft version. A 1.20.1 jar does not load on 1.21.1.

Fix. Match the artifact name exactly. The pattern is vsu-<minecraft>-<loader>-2.2.0.jar, and there are nine valid combinations listed on Installation.

Related. On 1.18.2, 1.19.2, and 1.20.1, Architectury API is a required dependency. A missing Architectury produces a dependency-resolution failure at startup rather than a VSU-specific error. Install Architectury for the same Minecraft version.

Java version mismatch#

Symptom. The loader reports an unsupported class file version or a Java requirement failure.

Cause. The lane's minimum is declared in the mod metadata: java >=17 on 1.18.2–1.20.1, java >=21 on 1.21.1, and a Java 25 toolchain on 26.1.2.

Fix. Run the server on the required JDK. Confirm before blaming the mod:

java -version

If the server wrapper picks a different JDK than your shell, check the start script's JAVA_HOME or the panel's Java version setting rather than the system default.

Commands are missing entirely#

Symptom. /vonixsu is unknown, and none of the VSU commands tab-complete.

Causes. The mod did not load. Check, in order:

1. The jar is in mods/, not plugins/ or the server root.
2. The server log has a [VonixSU] Initialized. line. Its absence means the mod never ran.
3. The loader's mod list contains vonix_server_utilities.
4. No dependency failure appears earlier in the log — Architectury on the older lanes, Fabric API on Fabric.
5. Two copies of the jar are not present in mods/. A duplicate produces a load-time conflict that can disable the mod entirely.

Collecting a diagnostic bundle#

When a problem needs a second pair of eyes, gather these before asking:

# 1. Version and platform
#    Run in game or console:
#    /vonixsu version
#    /vonixsu status

# 2. The configuration and kit file
tar czf vsu-diag-config.tar.gz -C config \
  vonix_server_utilities.properties vonix_server_utilities/kits.json

# 3. A consistent database snapshot
sqlite3 config/vonix_server_utilities/data.db ".backup '/tmp/vsu-diag.db'"

# 4. The relevant log slice
grep -nE "VonixSU|vonix_server_utilities" logs/latest.log > vsu-diag-log.txt

Include:

• The exact Minecraft version, loader, and loader version.
• The Java version from java -version.
• Whether LuckPerms is installed, and its version.
• The full text of any VSU error, not just the first line.
• What you changed immediately before the problem appeared.

Do not include the database if it contains player data you are not free to share; the log slice and config archive usually answer the question on their own. There are no credentials in a VSU install to redact.

Quick reference#