Skip to content
Vonix Network Wiki

Cross-Mod Diagnostic & Troubleshooting Index

State: current development/testing diagnostics

Use this index to match a symptom to a component, then follow the product-specific runbook.

Current Dev/Test

1. Symptom matrix

Section titled “1. Symptom matrix”
Symptom / error Component Likely cause Immediate action
UnsatisfiedLinkError: NativeDB VonixGuardian Relocated sqlite-jdbc breaking native JNI symbols Use the current unrelocated JarInJar artifact. Remove older shaded jars.
ResolutionException: Module contains package org.sqlite VonixGuardian JDBC classes exposed on the JPMS module path Use 3.0.0-m1 artifacts that nest the driver in META-INF/jars/ or META-INF/jarjar/.
database locked (SQLite) Both Network filesystem or backup tool holding the file Keep the server directory on local storage. Confirm WAL (PRAGMA journal_mode=WAL).
Players locked out of /home / /tpa VSU Historical v1.6.0 LuckPerms-authoritative check Run VSU 2.0.2 (union semantics). Check for explicit negative nodes.
Queue dropped N events VonixGuardian Write throughput cannot keep up with event rate Raise queue.maxSize / batchSize, or migrate to PostgreSQL.
TempMute not blocking the first message VSU Historical race between chat and async insert Run the 1.7.1 / 2.0.2 line, which applies mute in memory first.
Command not found during early startup Both Command registration before engine boot Wait for the server Done (Xs)! line.
owo.mixins.json:MainMixin injection failed External pack Third-party mixin conflict External boundary. Confirm VonixGuardian still loaded without hopper errors.

2. SQLite locking

Section titled “2. SQLite locking”

Both mods use local SQLite files:

  • VonixGuardian: vonixguardian.db
  • VSU: config/vonix_server_utilities/data.db
  1. Stop the server with /stop. Do not kill -9 while WAL is flushing.
  2. Inspect lock/WAL files:
    Terminal window
    ls -la config/vonix_server_utilities/
    # If data.db-wal exists, start and stop the server once so SQLite can checkpoint.
  3. Integrity check:
    Terminal window
    sqlite3 config/vonix_server_utilities/data.db "PRAGMA integrity_check;"
    sqlite3 vonixguardian.db "PRAGMA integrity_check;"

3. VonixGuardian queue drops

Section titled “3. VonixGuardian queue drops”

If /vg status reports dropped events:

  1. Inspect write latency with /vg status. Sustained p99 above 500 ms usually means disk saturation.
  2. Count recent events: 
    /vg lookup t:5m #count
  3. Reduce noise in config/vonixguardian/config.json with blockBlacklist and sourceBlacklist.

4. Permission mismatches

Section titled “4. Permission mismatches”
  1. Enable LuckPerms verbose logging: 
    /lp verbose on <player>
  2. For VSU, non-ops inherit opFallback = 0 commands. If /spawn is denied, check for an explicit negative node: 
    /lp user <player> permission check vsu.command.spawn
  3. For VonixGuardian without LuckPerms, confirm defaultOpLevel and that staff hold vanilla op 3 or 4: 
    /op <player>

Product runbooks: