Troubleshooting

Common Minecraft issues and solutions

Troubleshooting Minecraft Servers

Common issues and their solutions for Minecraft servers.

Server Won’t Start

Check Console Output

Always read the console for error messages. Common issues:

Java Version Mismatch

Error: A JNI error has occurred
UnsupportedClassVersionError

Solution: Use correct Java version

• 1.17-1.20.4: Java 17
• 1.20.5+: Java 21
• 1.16.5 and below: Java 8 or 11

Out of Memory

java.lang.OutOfMemoryError: Java heap space

Solution:

• Upgrade server RAM
• Check Xmx setting in startup
• Remove memory-heavy mods/plugins

EULA Not Accepted

You need to agree to the EULA

Solution:

1. Open eula.txt
2. Change eula=false to eula=true
3. Save and restart

Port Already in Use

Failed to bind to port
Address already in use

Solution:

• Wait for previous instance to fully stop
• Check if another server uses the port
• Contact support

Corrupted JAR File

Invalid or corrupt jarfile

Solution:

1. Delete the server JAR
2. Reinstall server software
3. Try different version

Mod/Plugin Conflicts

Caused by: java.lang.NoClassDefFoundError

Solution:

1. Remove all mods/plugins
2. Add back one at a time
3. Identify the problematic file

Connection Issues

Players Can’t Connect

”Can’t resolve hostname”

Solution:

• Verify IP address is correct
• Include port if not 25565 (IP:PORT)
• Wait for DNS propagation if using domain

”Connection refused”

Solution:

• Check if server is running
• Verify correct port
• Server may still be starting

”Connection timed out”

Solution:

• Server may be overloaded
• DDoS protection may be filtering
• Contact support if persistent

”Outdated client/server”

Solution:

• Match client version to server version
• Use ViaVersion for multi-version support

Kicked While Playing

”Timed out”

Solution:

• Server may be lagging
• Check player’s internet connection
• Reduce server load

”Internal server error”

Solution:

• Check console for errors
• Usually plugin/mod related
• Remove recently added plugins

Performance Issues

Server Lag (Low TPS)

Check TPS with /tps command:

• 20 TPS = Normal
• 15-19 TPS = Slight lag
• Below 15 TPS = Noticeable lag

Causes & Solutions

Symptom	Likely Cause	Solution
Lag when exploring	Chunk generation	Pre-generate world
Lag with many players	Entity overload	Reduce mob limits
Constant lag	Bad plugin	Profile with Spark
Lag during redstone	Complex machines	Limit redstone

See Performance Optimization for detailed fixes.

High RAM Usage

Normal causes:

• More players online
• Larger worlds
• More plugins/mods

Solutions:

• Upgrade RAM
• Optimize world settings
• Remove unnecessary plugins
• Clear old player data

Chunks Loading Slowly

Solutions:

1. Lower view-distance in server.properties
2. Pre-generate world with Chunky
3. Use Paper for async chunk loading
4. Ensure adequate RAM

Plugin Issues

Plugin Not Loading

[ERROR] Could not load 'plugins/PluginName.jar'

Common causes:

1. Wrong Minecraft version
2. Missing dependencies
3. Corrupted download
4. Wrong server type (needs Spigot but on Paper)

Solution:

1. Check plugin requirements
2. Install dependencies
3. Re-download plugin
4. Check for updates

Plugin Commands Not Working

Checklist:

1. Plugin loaded? Check /plugins
2. Have permission? Check with LuckPerms
3. Correct syntax? Check plugin docs
4. Plugin enabled? Some need enabling

Plugin Conflicts

Symptoms:

• Random errors
• Features not working
• Server crashes

Solution:

1. Identify conflicting plugins
2. Remove one or update both
3. Check plugin compatibility notes

Mod Issues

Mod Version Mismatch

Mod X requires version Y.Z of Minecraft

Solution: Download mod version matching your Minecraft version

Missing Dependencies

Mod X requires mod Y

Solution: Install the required mod

Forge/Fabric Crash

1. Check crash-reports folder
2. Look for the mod causing issues
3. Remove or update that mod
4. Check for version compatibility

World Issues

Corrupted World

Symptoms:

• Server crashes when loading
• Chunks appearing wrong
• Missing blocks

Solutions:

1. Restore from backup
2. Use MCEdit/MCASelector to repair
3. Delete corrupted region files

Chunks Resetting

Causes:

• World not saving properly
• Corrupted chunks
• Force kills instead of graceful stops

Prevention:

• Always use proper stop commands
• Regular backups
• Don’t force kill

Wrong Spawn Point

/setworldspawn

Or edit spawn coordinates in level.dat.

Common Error Messages

”A fatal error has been detected by the Java Runtime”

Solution:

• Java installation issue
• Try different Java version
• Contact support for Docker image change

”Exception in thread ‘main’”

Check the specific error that follows:

• ClassNotFoundException: Missing dependency
• FileNotFoundException: Missing file
• IOException: File permission or disk issue

”Server is still starting”

Wait longer - first startup takes time, especially with mods.

”Could not reserve enough space for object heap”

Solution:

• Server doesn’t have enough RAM
• Reduce Xmx value
• Upgrade plan

Getting Help

Information to Provide

When contacting support, include:

1. Full console output
2. Server type and version
3. List of plugins/mods
4. Steps to reproduce issue
5. When it started happening

Where to Get Help

1. Check this knowledge base
2. Search plugin/mod documentation
3. Discord Community
4. Open a Support Ticket

Prevention Tips

1. Regular backups - Before any changes
2. Update gradually - Don’t update everything at once
3. Test locally - Try changes in singleplayer first
4. Monitor performance - Use Spark regularly
5. Keep logs - Don’t clear console output until stable
6. Document changes - Note what you modify