Troubleshooting

Quick Diagnostics

Before diving into specific issues, run these basic checks:

Verify mod is loaded

Check server logs on startup for:

[voxy worldgen] voxy world gen initialized

Check F3 debug stats

Press F3 in-game. You should see stats in bottom-right corner:

[voxy worldgen v2] running

If nothing appears, set showF3MenuStats: true in config.

Verify config file exists

Look for config/voxyworldgenv2.json in your Minecraft directory.If missing, the mod will auto-create it on first run.

Common Issues

Chunks Not Generating

Generation is disabled in config

Symptom: F3 stats show no activity, remaining count is 0Cause: enabled: false in configFix:

Open config/voxyworldgenv2.json
Set "enabled": true
Save the file - config reloads automatically

Verification: F3 stats should update within 5 seconds showing generation activity.

No players are online

Symptom: Server running but F3 shows “remaining: 0”Cause: Generation is player-centric. Worker thread sleeps when no players are online (see ChunkGenerationManager.java:174-176).Fix: Join the server. Generation starts automatically based on your position.Code behavior:

if (players.isEmpty()) {
    Thread.sleep(1000);
    continue;
}

TPS throttling is active

Symptom: F3 shows “throttled (low tps)” in redCause: Server TPS dropped below 18, automatic protection engaged (see TpsMonitor.java:40-44).Fix:

Identify cause of low TPS

Too many players?
Other mods causing lag?
maxActiveTasks too high?

Reduce generation load

Edit config/voxyworldgenv2.json:

{
  "maxActiveTasks": 12  // Reduce by 50%
}

Wait for TPS recovery

Throttling automatically disables when MSPT drops below 55.5ms. Check F3 stats - should change to “running” in green.

Prevention: See Optimization Guide for proper task tuning.

Already generated (skipped chunks)

Symptom: F3 shows high “skipped” count, low “completed” countCause: Chunks were previously generated and saved. The mod tracks completion in voxy_gen_*.bin files (see ChunkPersistence.java:21).Fix: This is normal behavior! Skipped chunks are already available - no action needed.To force regeneration:

This deletes generation progress. Only do this if chunks are corrupted.

Stop the server
Delete world/voxy_gen_minecraft_dimension_*.bin files
Restart server

Chunks will be treated as “new” and regenerated.

Player is in different dimension

Symptom: Generation works in Overworld but not Nether/EndCause: The mod switches dimensions based on where most players are (see ChunkGenerationManager.java:409-423).Fix:

Single player: Generation follows you automatically
Multiplayer: Majority of players must be in the dimension you want generated

Example: 3 players in Overworld, 1 in Nether → generates Overworld. To generate Nether, all 4 players must enter Nether.Code reference:

// Switches to dimension with most players
if (entry.getValue() > maxCount) {
    maxCount = entry.getValue();
    majorLevel = entry.getKey();
}

Performance Issues

Server TPS drops when generation is active

Symptom: Lag, F3 shows < 18 TPSCause: maxActiveTasks exceeds server capacityImmediate fix:Edit config/voxyworldgenv2.json:

{
  "maxActiveTasks": 8  // Start low
}

Save and wait 10 seconds. TPS should recover.Long-term fix:

Start with maxActiveTasks: 8
Increase by 4 every 5 minutes
Stop increasing when TPS drops below 19
Use that value - 4 as your optimal setting

See also: Optimization Guide

Generation is very slow (< 5 c/s)

Symptom: F3 shows low “rate”, long ETACauses and fixes:

Low maxActiveTasks
- Current value too conservative
- Fix: Increase by 50% and monitor TPS
Disk bottleneck (HDD)
- Saves are slow on spinning disks
- Fix: Set "saveNormalChunks": false or upgrade to SSD
CPU bottleneck
- Other processes using CPU
- Fix: Close unnecessary programs, allocate more cores to Minecraft
Auto-throttling
- Check if F3 shows “throttled”
- Fix: See “TPS throttling is active” above

Benchmark: Most servers should achieve 15-40 c/s. See Optimization Guide.

High memory usage

Symptom: Java heap usage grows unbounded, OutOfMemoryErrorCauses:

generationRadius too large
- Radius 256 = 204,800 chunks to track
- Fix: Reduce to 128 or 64
saveNormalChunks disabled with high radius
- Chunks stay in memory instead of saving to disk
- Fix: Enable "saveNormalChunks": true
Insufficient heap allocation
- Minecraft needs more RAM
- Fix: Increase -Xmx JVM argument (e.g., -Xmx8G for 8GB)

Memory-efficient config:

{
  "generationRadius": 64,
  "saveNormalChunks": true,
  "maxActiveTasks": 16
}

Voxy Integration Not Working

Voxy mod not installed

Symptom: F3 shows “voxy: disabled” in redCause: Voxy mod is not present in mods/ folderFix:

Download Voxy

Get the latest version from Modrinth or CurseForge

Install to mods folder

Place voxy-*.jar in your mods/ directory

Restart Minecraft

Full restart required (not just reload)

Verify integration

Check logs for:

[voxy worldgen] voxy integration initialized (enabled: true)

F3 should now show “voxy: enabled” in green

Voxy installed but not detected

Symptom: Voxy mod is in mods folder, but F3 shows “disabled”Cause: Version incompatibility or initialization failureFix:

Check server logs for errors:

[voxy worldgen] failed to initialize voxy integration

Version mismatch:
- Ensure Voxy version matches your Minecraft version
- Example: Minecraft 1.21.4 needs Voxy 1.21.4
API changes:
- Voxy may have changed internal APIs
- Update both mods to latest versions
Reflection failure:
- Check if Java security manager blocks reflection
- Ensure no -Djava.security.manager JVM arg

Chunks generate but don't appear in LOD view

Symptom: F3 shows chunks completing, but distant terrain not visibleCauses:

Ingestion failed silently
- Check logs for:
  [voxy worldgen] failed to ingest chunk
- Usually means Voxy internal error
Voxy not rendering LODs
- This is a Voxy issue, not Voxy World Gen
- Check Voxy’s own debug screen
- Verify LOD storage in voxy_data/ folder
Client-side only mod
- On multiplayer, client must have Voxy installed
- Server generates, client renders

Debugging:

Enable verbose logging in Voxy’s config
Check logs/latest.log for ingestion calls
Verify VoxyIntegration.java:88-92 is executing without exceptions

Configuration Issues

Config file not saving

Symptom: Edit config, but changes revert on restartCauses:

File permissions
- Config directory is read-only
- Fix (Linux/Mac):
  chmod 755 config chmod 644 config/voxyworldgenv2.json
- Fix (Windows): Right-click folder → Properties → Uncheck “Read-only”
Invalid JSON syntax
- Parsing fails, defaults loaded instead
- Fix: Validate JSON at jsonlint.com
- Check logs for:
  [voxy worldgen] failed to save config
File locked by another process
- Editor or backup software has file open
- Fix: Close all editors, wait 10 seconds, try again

Config changes not applying

Symptom: Edit config, save, but behavior doesn’t changeCauses:

Edited wrong file
- Multiple Minecraft instances (client/server)
- Fix: Confirm path:
  - Server: server_folder/config/voxyworldgenv2.json
  - Client: %appdata%/.minecraft/config/voxyworldgenv2.json (Windows)
Requires restart
- Most settings hot-reload, but verify in logs:
  [voxy worldgen] Config reloaded
- If not seen, restart server

Typo in parameter name

Example: maxActiveTask instead of maxActiveTasks

Fix: Compare against default config:

{
  "enabled": true,
  "showF3MenuStats": true,
  "generationRadius": 128,
  "maxActiveTasks": 20,
  "saveNormalChunks": true
}

F3 stats not showing

Symptom: Press F3, no Voxy stats in cornerFixes:

Enable in config:
```
{
  "showF3MenuStats": true
}
```
Check you’re pressing F3 correctly:
- Opens Minecraft debug screen
- Stats appear in bottom-right (not top-left)
Verify client-side mod installed:
- F3 stats render client-side
- Multiplayer: client needs Voxy World Gen V2 installed
GUI scale too large:
- Stats render off-screen
- Reduce GUI scale in Video Settings

Multiplayer Specific Issues

Clients not receiving LOD data

Symptom: Server generates chunks, but clients don’t see themCause: Client doesn’t have the mod or network desyncFix:

Install client-side

Every player must have Voxy World Gen V2 in their mods/ folder

Verify handshake

Check client logs for:

[voxy worldgen] Received server handshake

Check network stats

F3 should show (on client):

[voxy worldgen v2] connected
rate: 15.2 c/s
bandwidth: 450 KB/s

If still failing: Check NetworkHandler.java:214 - server sends handshake on join. Firewall or network issue may block packets.

High bandwidth usage

Symptom: Network saturated, lagCause: LOD data packets are chunk-sized (several KB each)Mitigation:

Reduce generation speed:
- Lower maxActiveTasks to reduce broadcast rate
Limit player spread:
- Players far apart trigger more unique generation
- Keep players in same area initially
Pre-generate offline:
- Generate world before players join
- Only sync already-generated chunks (fast)

Code reference: NetworkHandler.java:143-159 broadcasts to all players within 4096 block radius.

Interpreting F3 Debug Stats

The F3 overlay provides real-time diagnostics. Here’s what each field means:

Singleplayer Stats

[voxy worldgen v2] running          ← Status: running / throttled / done
completed: 45.2K                    ← Chunks generated this session
skipped: 1.3K                       ← Chunks loaded from disk (already existed)
lod suppressed: 890                 ← Chunks not saved (saveNormalChunks: false)
remaining: 5847 (3m 12s)            ← Chunks left in radius + ETA
active: 24                          ← Current concurrent tasks
rate: 25.3 c/s                      ← Chunks per second (10s average)
voxy: enabled                       ← Voxy integration status

Code reference: DebugRenderer.java:62-74

Multiplayer Stats (Client View)

[voxy worldgen v2] connected        ← Server has mod and is sending data
rate: 18.7 c/s                      ← Chunks received per second
bandwidth: 425 KB/s                 ← Network throughput
received: 12.4K (145 MB)            ← Total chunks + data received
voxy: enabled                       ← Local Voxy integration

Code reference: DebugRenderer.java:76-83

Status Indicators

running (green): Normal operation
throttled (red): TPS protection active, generation paused
done (green): All chunks in radius completed
connected (green): Client receiving server data
voxy-server: offline (red): Server doesn’t have mod or hasn’t sent handshake

Log Analysis

Key log messages and what they mean:

Startup Logs

[voxy worldgen] voxy world gen initialized

✅ Mod loaded successfully

[voxy worldgen] voxy integration initialized (enabled: true)

✅ Voxy detected and integrated

[voxy worldgen] voxy not present, integration disabled

⚠️ Voxy not found (expected if you don’t have Voxy)

Runtime Logs

[voxy worldgen] tellus world detected for minecraft:overworld, enabling fast generation

✅ Tellus integration active for this dimension

[voxy worldgen] loaded 45234 chunks from voxy generation cache for ResourceKey[minecraft:dimension/overworld]

✅ Restored previous generation progress

[voxy worldgen] error in worker loop

❌ Generation error - check full stack trace

Shutdown Logs

[voxy worldgen] server stopping, shutting down manager

✅ Clean shutdown initiated

Getting Help

If you’ve tried the above and still have issues:

Gather diagnostics

Full latest.log file
Screenshot of F3 stats
Config file contents
Mod list (if multiplayer, both client and server)

Check existing issues

Search the GitHub Issues for similar problems

Report bug

If not found, open a new issue with:

Minecraft version
Mod version
Detailed description of problem
Steps to reproduce
Diagnostic info from step 1

Get Started

Core Concepts

Configuration

Integrations

Guides

Quick Diagnostics

Common Issues

Chunks Not Generating

Performance Issues

Voxy Integration Not Working

Configuration Issues

Multiplayer Specific Issues

Interpreting F3 Debug Stats

Singleplayer Stats

Multiplayer Stats (Client View)

Status Indicators

Log Analysis

Startup Logs

Runtime Logs

Shutdown Logs

Getting Help

Next Steps

Optimization

Multiplayer Setup

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Integrations

Guides

​Quick Diagnostics

​Common Issues

​Chunks Not Generating

​Performance Issues

​Voxy Integration Not Working

​Configuration Issues

​Multiplayer Specific Issues

​Interpreting F3 Debug Stats

​Singleplayer Stats

​Multiplayer Stats (Client View)

​Status Indicators

​Log Analysis

​Startup Logs

​Runtime Logs

​Shutdown Logs

​Getting Help

​Next Steps

Optimization

Multiplayer Setup

Build docs developers (and LLMs) love

Quick Diagnostics

Common Issues

Chunks Not Generating

Performance Issues

Voxy Integration Not Working

Configuration Issues

Multiplayer Specific Issues

Interpreting F3 Debug Stats

Singleplayer Stats

Multiplayer Stats (Client View)

Status Indicators

Log Analysis

Startup Logs

Runtime Logs

Shutdown Logs

Getting Help

Next Steps