VonixGuardian — Troubleshooting & Operations

Candidate Line: 3.0.0-m1 Operational Diagnostic RunbookCurrent Dev/Test

This guide addresses operational issues, database backpressure symptoms, loader lifecycle edge cases, and known external pack boundaries.

1. Quick Diagnostic Checklist

Run /vg status in console or as an operator. Verify:

1. DB Connection: Status reports OK with active connection pool.
2. Queue Depth: Queue should be 0 or low under idle server conditions.
3. Dropped Events: Must read 0. A non-zero drop count indicates storage write saturation.
4. Bootstrap Completed: Confirm that VonixGuardian bootstrap complete. logged prior to server Done.

---

2. Common Errors & Resolutions

“Server boots but no VonixGuardian load line appears”

• Cause: Loader descriptor mismatch or Java version mismatch. Forge expects mandatory = true in mods.toml, while NeoForge expects type = "required".
• Remedy: Ensure you did not copy a Forge jar onto a NeoForge 1.21.1+ server. Verify that the runtime Java version matches (Java 17 for 1.18.2–1.20.1, Java 21 for 1.21.1, Java 25 for 26.1.2).

---

“ResolutionException: Module vonixguardian contains package org.sqlite”

• Cause: Running an older or improperly packaged jar where SQLite driver classes were placed directly at the jar root, colliding with the loader’s JPMS module path.
• Remedy: Current 3.0.0-m1 artifacts bundle sqlite-jdbc strictly inside META-INF/jars/ (Fabric) or META-INF/jarjar/ (Forge/NeoForge). Ensure old development jars are purged from mods/.

---

“UnsatisfiedLinkError on first DB op”

• Cause: Shaded/relocated sqlite-jdbc destroys native C symbols. The native .so/.dll binary expects Java_org_sqlite_core_NativeDB_*. If a build relocates Java classes to ...shadow.sqlite..., the JVM cannot bind JNI symbols.
• Remedy: Current candidate artifacts strictly use unrelocated JarInJar packaging for all JDBC drivers. Upgrade to the current 3.0.0-m1 build.

---

“Queue dropped N events” in console

• Cause: Event creation rate exceeds database write throughput, and queue.maxSize (default 50,000) was breached. To prevent Minecraft tick stalling, VonixGuardian drops excess events rather than blocking the game thread.
• Remedy:
  1. Increase buffer capacity in config/vonixguardian/config.json:

     "queue": {
       "maxSize": 200000,
       "batchSize": 2500,
       "flushIntervalMs": 2500
     }

  2. If SQLite write latency stays high, migrate to PostgreSQL with /vg migrate-db postgresql CONFIRM during a maintenance window. The “> 50 players” figure is a planning heuristic, not a measured live-server threshold.

---

“/vg command not recognised immediately after startup”

• Cause: On certain loaders, RegisterCommandsEvent fires before the core Guardian.boot() worker finishes.
• Remedy: 3.0.0-m1 implements a deferred dispatcher capture and registration replay pattern. If this occurs on customized loaders, verify that the server has completed its full boot cycle (Done (Xs)!) before issuing commands.

---

3. High-Frequency Event Storms & Coalescing

In heavily modded packs, certain entities (e.g., dragons breaking blocks or custom quarry contraptions) fire hundreds of thousands of prospective block queries per second (LivingDestroyBlockEvent).

VonixGuardian handles this via the producer-side EntityBlockChangeCoalescer:

• Coalesces rapid sequential queries for identical coordinates into a single unified record.
• Discards air-to-air physics queries before they enter the async queue.
• If a modpack generates excessive noise, add the offending block or source tag to blockBlacklist or sourceBlacklist in config.json.

---

4. Known Validation Boundaries

External Modpack Validation Boundary

During headless testing of the Fabric 1.21.1 path on an external modpack, VonixGuardian loaded cleanly with zero hopper-helper errors. However, the full pack failed to reach readiness due to an unrelated third-party library error: owo.mixins.json:MainMixin afterQuiltHook injection failed.

This is an external dependency boundary between owo-lib and Quilt/Fabric mixin hooks in that specific pack snapshot, not a VonixGuardian crash.

Hopper & Dispenser Repairs in Current Testing

The current testing candidate explicitly removes the invalid non-private hopper snapshot helper from all nine HopperBlockEntityMixin cells, while preserving the Forge dispenser event repair.