Troubleshooting

Common problems and their solutions when running Lumo Server.

Server Won’t Start

EULA Not Accepted

Symptoms:

EULA not accepted. Set EULA=true to accept the Minecraft EULA

Solution:

docker run -e EULA=true ...

Insufficient Memory

Symptoms:

• Container exits immediately
• Error: “Could not reserve enough space for object heap”

Solution:

# Reduce memory allocation
-e MEMORY=2G  # Instead of 4G or more

# Or increase Docker memory limit
# Docker Desktop → Settings → Resources → Memory

Port Already in Use

Symptoms:

Address already in use
bind: address already in use

Solution:

# Find what's using port 25565
lsof -i :25565  # Mac/Linux
netstat -ano | findstr :25565  # Windows

# Kill the process or use different port
-p 25566:25565  # Map to different external port

Connection Issues

Can’t Connect to Server

Check server is running:

docker ps

Check logs:

docker logs minecraft-server | tail -50

Verify port mapping:

docker port minecraft-server
# Should show: 25565/tcp -> 0.0.0.0:25565

Test connectivity:

# From server host
nc -zv localhost 25565

# From another machine
nc -zv server-ip 25565

Common causes:

• Firewall blocking port 25565
• Server not finished starting (wait for “Done” in logs)
• Wrong server address
• Autopause active (server sleeping - retry connection)

“Server is sleeping” Message

This is normal when autopause is enabled.

Solution: Wait 5-10 seconds and reconnect. Server is waking up.

Disable if problematic:

-e ENABLE_AUTOPAUSE=false

Performance Issues

Server Laggy / Low TPS

Check TPS:

docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft "tps"

Healthy TPS: 19-20. Below 15 indicates lag.

Solutions:

1. Increase memory:

   -e MEMORY=6G  # or higher

2. View distance:

   -e VIEW_DISTANCE=10  # Reduce from 12

3. Pre-generate chunks:

   docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
     "chunker start lumo_wilds 5000"

4. Check entity count:

   docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
     "forge entity list"

5. Restart server:

   docker restart minecraft-server

High Memory Usage

Check memory:

docker stats minecraft-server

Solutions:

1. Adjust heap size:

   -e MEMORY=4G  # Match your available RAM

2. Clear plugin data:

   • CoreProtect database can grow large
   • Clean old backups
   • Reduce chunk loading

Autopause Not Working

Check if enabled:

docker logs minecraft-server | grep -i autopause

Common issues:

1. Kubernetes health checks: Disable autopause in K8s

2. Chunk loaders: Plugins keeping chunks loaded prevent pause

3. Verify process:

   docker exec minecraft-server ps aux | grep autopause

Plugin Issues

Plugin Won’t Load

Check logs:

docker logs minecraft-server | grep -i "PluginName"

Common causes:

1. Incompatible version:

   • Plugin requires different Paper version
   • Check plugin compatibility

2. Missing dependency:

   # Example: WorldGuard needs WorldEdit
   docker logs minecraft-server | grep -i "dependency"

3. Corrupted config:

   # Delete config to regenerate
   docker exec minecraft-server rm /data/plugins/PluginName/config.yml
   docker restart minecraft-server

Plugin Config Not Updating

Ensure you’re editing the right location:

# WRONG - This is the default, gets overwritten
/server/plugins/PluginName/config.yml

# CORRECT - This is persistent
/data/plugins/PluginName/config.yml

Reload plugin:

docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
  "pluginname:reload"

Or reload all:

docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
  "reload confirm"

RCON Issues

RCON Connection Refused

Check RCON is enabled:

docker logs minecraft-server | grep -i rcon

Verify password:

# Default password is "minecraft"
docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft "list"

Test from outside:

# Install mcrcon locally first
mcrcon -H server-ip -P 25575 -p minecraft "list"

Common issues:

• RCON takes 10-30s to initialize after startup
• Wrong password
• Port 25575 not exposed: -p 25575:25575

World Issues

World Not Created

Check init-worlds logs:

docker logs minecraft-server | grep -i "init-worlds"

Manual creation:

docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
  "mv create worldname NORMAL"

If RCON timeout:

• Server may not be fully started
• RCON password mismatch
• Plugin conflict

Terralith Not Working

Symptoms: Standard terrain in lumo_wilds

Fix:

1. Stop server
2. Delete lumo_wilds world
3. Restart (init-worlds.sh will recreate with Terralith)

docker stop minecraft-server
docker exec minecraft-server rm -rf /data/lumo_wilds
docker start minecraft-server

Can’t Teleport Between Worlds

Check Multiverse:

docker logs minecraft-server | grep -i multiverse

Reload Multiverse:

docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
  "mv reload"

List worlds:

docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
  "mv list"

Backup Issues

Backups Not Running

Check logs:

docker logs minecraft-server | grep -i backup

Verify enabled:

docker inspect minecraft-server | grep BACKUP_ENABLED

Manual test:

docker exec minecraft-server python3 /backup.py

Backup Failed - Disk Space

Check space:

df -h /var/lib/docker/volumes/

Clean old backups:

docker run --rm -v minecraft_backups:/backups \
  ghcr.io/lucasilverentand/lumo-server:latest \
  find /backups -name "*.tar.gz" -mtime +30 -delete

S3 Upload Failed

Test credentials:

docker exec minecraft-server aws s3 ls s3://your-bucket

Check endpoint:

docker logs minecraft-server | grep "S3 upload"

Verify ENV vars:

docker inspect minecraft-server | grep -E "S3_|AWS_"

BlueMap Issues

BlueMap Not Accessible

Verify port:

# Must expose port 8100
-p 8100:8100

Check web server started:

docker logs minecraft-server | grep -i bluemap

Access: http://server-ip:8100

Common issues:

• Port not exposed
• Firewall blocking 8100
• BlueMap still rendering (check logs)

BlueMap Not Rendering

Check config:

docker exec minecraft-server cat /data/plugins/BlueMap/core.conf

Force render:

docker exec minecraft-server mcrcon -H localhost -P 25575 -p minecraft \
  "bluemap reload"

Voice Chat Issues

Voice Chat Not Working

Verify UDP port:

# MUST be UDP, not TCP
-p 24454:24454/udp

Check plugin loaded:

docker logs minecraft-server | grep -i voicechat

Client requirements:

• Voice chat mod installed on client
• Correct server IP and port

Permission Issues

File Permission Errors

Fix permissions:

docker exec minecraft-server chown -R minecraft:minecraft /data

Volume permission issues:

# If using bind mounts, ensure host directory is writable
sudo chown -R 1000:1000 /path/to/minecraft-data

Container Issues

Container Exits Immediately

Check exit code:

docker ps -a
# Look at STATUS column

View logs:

docker logs minecraft-server

Common causes:

• EULA not accepted
• Memory allocation too high
• Port conflict
• Corrupted data

Container Running But Server Not Responding

Check processes:

docker exec minecraft-server ps aux

Java should be running - if not, server crashed.

Check health:

docker inspect --format='{{json .State.Health}}' minecraft-server

Data Loss Prevention

Backup Before Major Changes

# Manual backup
docker exec minecraft-server python3 /backup.py

# Or full volume backup
docker run --rm -v minecraft_data:/data -v $(pwd):/backup \
  alpine tar -czf /backup/emergency-backup.tar.gz /data

Test Restores Regularly

# Test restore in temporary container
docker run -d --name mc-test \
  -e EULA=true \
  -v minecraft_test:/data \
  -v minecraft_backups:/backups \
  ghcr.io/lucasilverentand/lumo-server:latest

docker exec mc-test /restore.sh backup-file.tar.gz

# Verify
docker logs mc-test

# Cleanup
docker rm -f mc-test
docker volume rm minecraft_test

Getting More Help

Enable Debug Logging

Add to server.properties (generate first, then edit):

debug=true

Collect Diagnostic Info

# Server version
docker exec minecraft-server cat /server/version.txt

# Plugin list
docker exec minecraft-server ls -la /server/plugins/

# Logs
docker logs minecraft-server > server-logs.txt

# Config
docker exec minecraft-server cat /data/server.properties > server-props.txt

Community Support

• GitHub Issues: github.com/lucasilverentand/lumo-server/issues
• Paper Discord: For Paper-specific issues
• Plugin Discords: For plugin-specific issues

Next Steps

• Environment Variables - Full configuration reference
• Architecture - Understand the internals
• Plugin Configuration - Configure plugins