Troubleshooting

Common issues and solutions for LilChunks

Troubleshooting Guide

Comprehensive solutions for common LilChunks issues and problems.

Quick Diagnostics

Before diving into specific issues, run these quick diagnostic checks:

1. Check Plugin Status

   Verify LilChunks is loaded and enabled:

   /plugins
   # Look for LilChunks in green
   

2. Test Basic Commands

   Try basic functionality:

   /lc help
   /lc status
   

3. Check Permissions

   Verify you have the required permissions:

   /lp user <username> permission check lilchunks.use
   /lp user <username> permission check lilchunks.admin
   

4. Review Server Logs

   Check for error messages:

   # Look for LilChunks-related errors
   tail -f logs/latest.log | grep -i lilchunks
   

Common Issues

Installation and Loading Issues

Plugin Not Loading

Symptoms:

• LilChunks doesn’t appear in /plugins list
• No startup messages in console
• Commands not recognized

Causes & Solutions:

Java Version

Problem: Using Java 16 or older

Solution: Upgrade to Java 17+

# Check Java version
java -version

# Should show Java 17 or higher
openjdk version "17.0.x" or higher

Version Compatibility Error

Symptoms:

[ERROR] This version of Minecraft is not supported!
[ERROR] Please use version 1.16.5 or higher.

Solutions:

1. Update Server: Upgrade to Minecraft 1.16.5 or higher
2. Check Version: Verify actual server version with /version
3. Update LilChunks: Ensure you have the latest version

Supported Versions:

• ✅ Minecraft 1.16.5 - 1.21.5
• ❌ Minecraft 1.16.4 and below

Configuration Errors

Symptoms:

[WARN] Invalid configuration value: chunks-per-tick
[WARN] Using default value: 4

Solutions:

1. Validate YAML: Check config.yml syntax
2. Reset Config: Delete config.yml to regenerate defaults
3. Check Values: Ensure all values are within valid ranges

# Backup and reset config
mv plugins/LilChunks/config.yml plugins/LilChunks/config.yml.backup
/lc reload

Command and Permission Issues

Command Not Found

Symptoms:

Unknown command. Type "/help" for help.

Solutions:

Plugin Not Loaded

Check: Is LilChunks loaded?

/plugins
# LilChunks should be green

Fix: Restart server or reload plugin

Permission Denied

Symptoms:

You don't have permission to use this command.

Solutions:

Grant Permissions

# Basic access
/lp user <username> permission set lilchunks.use true

# Admin access
/lp user <username> permission set lilchunks.admin true

# Or use OP
/op <username>

Generation Issues

Generation Won't Start

Symptoms:

Failed to start chunk generation.

Diagnostic Steps:

1. Check Current Status

   /lc status
   # Is generation already running?
   

2. Verify World Access

   # Can you access the world?
   /tp 0 100 0
   

3. Check Server Resources

   /tps
   /memory
   # Is server overloaded?
   

4. Try Smaller Radius

   # Start with minimal test
   /lc start 1
   

Common Causes:

• Generation already running in world
• Insufficient server resources
• World protection plugins blocking access
• Invalid world or location

Generation Stops Unexpectedly

Symptoms:

• Generation stops without completing
• No error messages
• Status shows “Stopped”

Investigation:

Check Logs

# Look for error messages
grep -i "lilchunks\|error\|exception" logs/latest.log

# Check for memory issues
grep -i "outofmemory\|gc" logs/latest.log

Very Slow Generation

Symptoms:

• Generation speed < 5 chunks/second
• Taking much longer than expected
• Server feels sluggish

Optimization Steps:

1. Check Current Settings

   # Review config.yml
   chunk-generation:
     chunks-per-tick: ?
     use-async: ?
   performance:
     use-parallel: ?
     thread-count: ?
   

2. Monitor Performance

   /tps
   /lc status
   # Note current speed
   

3. Adjust Configuration

   # Try these optimizations
   chunk-generation:
     chunks-per-tick: 2  # Reduce if TPS low
     use-async: true
   performance:
     use-parallel: true
     thread-count: 0  # Auto-detect
   

4. Reload and Test

   /lc reload
   /lc status
   # Check if speed improved
   

Performance Issues

Server Lag During Generation

Symptoms:

• TPS drops below 15
• Players experience lag
• Server feels unresponsive

Immediate Actions:

1. Check TPS

   /tps
   # If below 15, take action immediately
   

2. Reduce Generation Speed

   # Edit config.yml
   chunk-generation:
     chunks-per-tick: 1  # Reduce significantly
   

   /lc reload
   

3. Consider Stopping

   # If TPS still low, stop generation
   /lc stop
   

4. Optimize Configuration

   # Use conservative settings
   chunk-generation:
     chunks-per-tick: 1
     generate-structures: false
     generate-features: false
   performance:
     use-parallel: false
     thread-count: 1
     max-memory-usage: 1024
   

Memory Issues

Symptoms:

java.lang.OutOfMemoryError: Java heap space

Solutions:

Increase Heap Size

# Increase JVM memory allocation
java -Xms4G -Xmx8G -jar server.jar

Advanced Troubleshooting

Debug Mode

Enable debug mode for detailed troubleshooting:

1. Enable Debug

   # Edit config.yml
   debug: true
   logging:
     detailed-logs: true
     progress-interval: 1
   

2. Reload Configuration

   /lc reload
   

3. Reproduce Issue

   # Try to reproduce the problem
   /lc start 5
   

4. Analyze Logs

   # Check detailed logs
   tail -f logs/latest.log | grep -i lilchunks
   

5. Disable Debug

   # Don't forget to disable when done
   debug: false
   logging:
     detailed-logs: false
   

Log Analysis

Common log patterns and their meanings:

Normal Operation

[INFO] [LilChunks] Started chunk generation for world: world
[INFO] [LilChunks] Generation progress: 50/441 chunks (11%)
[INFO] [LilChunks] Generation completed for world: world

Meaning: Everything working normally

Plugin Conflicts

Common plugin conflicts and solutions:

World Management Plugins

Conflicting Plugins: Multiverse, MyWorlds, WorldEdit

Issues:

• World protection preventing generation
• Conflicting world loading/unloading
• Permission conflicts

Solutions:

1. Temporarily disable conflicting plugins
2. Configure world protection to allow LilChunks
3. Use different worlds for testing

Performance Plugins

Conflicting Plugins: ClearLag, LagMonitor, TickThreading

Issues:

• Interference with chunk loading
• Memory management conflicts
• Thread management issues

Solutions:

1. Configure plugins to ignore LilChunks processes
2. Adjust timing settings
3. Test with plugins disabled

Protection Plugins

Conflicting Plugins: WorldGuard, GriefPrevention, Towny

Issues:

• Chunk generation blocked by protection
• Permission conflicts
• Region conflicts

Solutions:

1. Grant LilChunks bypass permissions
2. Configure protection to allow generation
3. Use unprotected areas for testing

Getting Help

Information to Provide

When seeking help, provide this information:

Server Information

# Server details
/version
java -version

# Plugin list
/plugins

# LilChunks version
/lc help

Support Channels

GitHub Issues

Report bugs and request features on the official repository

Discord Community

Get help from the community and developers

Documentation

Check the complete documentation for solutions

Wiki

Community-maintained troubleshooting guides

Prevention Tips

🔄 Regular Maintenance

• Keep LilChunks updated to the latest version
• Regularly review and optimize configuration
• Monitor server performance during generation
• Backup worlds before large pregeneration tasks

📊 Performance Monitoring

• Set up automated TPS monitoring
• Use memory monitoring tools
• Keep logs of successful configurations
• Document what works for your server

🧪 Testing

• Test new configurations on development servers
• Start with small generation tasks
• Gradually increase generation size
• Monitor impact on player experience

📚 Stay Informed

• Read update changelogs
• Follow best practices guides
• Join community discussions
• Share experiences with others

Emergency Procedures

Server Unresponsive

If LilChunks causes server to become unresponsive:

1. Force Stop Server

   # Kill server process
   pkill -f "java.*server.jar"
   
   # Or use server management tools
   screen -r minecraft
   # Ctrl+C to force stop
   

2. Disable LilChunks

   # Rename plugin to prevent loading
   mv plugins/lilchunks*.jar plugins/lilchunks*.jar.disabled
   

3. Start Server

   # Start server without LilChunks
   java -jar server.jar
   

4. Investigate Issue

   # Check logs for errors
   grep -i "error\|exception\|outofmemory" logs/latest.log
   
   # Review configuration
   cat plugins/LilChunks/config.yml
   

5. Fix and Re-enable

   # Fix configuration issues
   # Re-enable plugin
   mv plugins/lilchunks*.jar.disabled plugins/lilchunks*.jar
   
   # Restart server
   

Next Steps

API Documentation

Learn about LilChunks API for developers

Performance Guide

Return to performance optimization guide