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

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

Problem: Incomplete or corrupted jar file

Solution: Re-download LilChunks

# Check file size (should be ~150KB)
ls -lh plugins/lilchunks*.jar

# Re-download if size is wrong

Problem: Unsupported server software

Solution: Use Bukkit/Spigot/Paper

# Check server version
/version

# Supported: Bukkit, Spigot, Paper 1.16.5+

Problem: Server can’t read the jar file

Solution: Fix file permissions

# Linux/Mac
chmod 644 plugins/lilchunks*.jar
chown minecraft:minecraft plugins/lilchunks*.jar

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

Check: Is LilChunks loaded?

/plugins
# LilChunks should be green

Fix: Restart server or reload plugin

Check: Using correct command syntax?

# Correct commands:
/lilchunks help
/lc help
/chunks help

Check: Another plugin using same command?

# Try full command name
/lilchunks:help
/lilchunks:start 10

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>

# 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>

# Check what permissions user has
/lp user <username> permission info

# Test specific permission
/lp user <username> permission check lilchunks.admin

# Check if permission plugin is working
/plugins

# Try without permission plugin (OP only)
/op <username>
/lc help

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

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

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

# Check if server ran out of resources
/tps
/memory

# Check disk space
df -h

# Disable other plugins temporarily
/plugins

# Test with minimal plugins

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

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

# Limit LilChunks memory usage
performance:
  max-memory-usage: 1024  # 1GB limit

# Use G1GC for better memory management
java -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -jar server.jar

chunk-generation:
  chunks-per-tick: 1
  generate-structures: false
  generate-caves: false
  generate-features: false

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

[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

[WARN] [LilChunks] Generation speed below optimal: 2 chunks/second
[WARN] [LilChunks] High memory usage detected: 85%

Action: Optimize configuration or reduce load

[ERROR] [LilChunks] Failed to generate chunk at 10, 15
[ERROR] [LilChunks] OutOfMemoryError during generation
[ERROR] [LilChunks] World not accessible: world_name

Action: Address specific error condition

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

# Server details
/version
java -version

# Plugin list
/plugins

# LilChunks version
/lc help

# Share your config.yml (remove sensitive info)
# Include relevant server.properties settings
# Include JVM arguments used

# Exact error messages
# Steps to reproduce
# When the issue started
# What you were trying to do

# TPS during issue
/tps

# Memory usage
/memory

# Generation status
/lc status

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

Assistant

Responses are generated using AI and may contain mistakes.