Hytale Server Troubleshooting Guide

Running into issues with your Hytale server? This troubleshooting guide covers common problems and their solutions to help you get back online quickly.

Server Won’t Start

Java Not Found or Wrong Version

Symptoms: Error about Java not found or unsupported version

Solution:

1. Verify Java is installed: java -version
2. Ensure Java 21+ is installed (64-bit)
3. Install OpenJDK 21 if needed:

   # Ubuntu/Debian
   sudo apt install openjdk-21-jdk

4. Verify correct version is active

Not Enough Memory

Symptoms: OutOfMemoryError, server crashes on start

Solution:

• Increase allocated RAM in startup script
• Ensure system has enough free memory
• Close other applications
• Check for memory leaks in plugins/mods

Port Already in Use

Symptoms: “Address already in use” error

Solution:

• Check if another server is running on the same port
• Kill the process using the port
• Or change your server to a different port

EULA Not Accepted

Symptoms: Server stops with EULA message

Solution:

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

Connection Issues

Players Can’t Connect

Check these in order:

1. Server running? – Verify server is online in console
2. Correct IP/Port? – Double-check connection details
3. Firewall? – Ensure port is open (UDP)
4. Port forwarding? – Verify router configuration
5. Server full? – Check max player count

Firewall Configuration

Windows:

# Run as Administrator
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 25565 -Action Allow

Linux (UFW):

sudo ufw allow 25565/udp
sudo ufw reload

Connection Timeout

Solutions:

• Wait for server to fully initialize
• Check network stability
• Verify port forwarding is correct
• Try connecting from same network first (local IP)

Version Mismatch

Solutions:

• Update client to match server version
• Or update server to match client
• Check for updates in launcher

Performance Issues

Server Lag / Low TPS

Causes and Solutions:

• Too many entities – Reduce mob caps, clear excess items
• High view distance – Lower view distance setting
• Inefficient plugins – Identify and remove problematic plugins
• World size – Set world borders, trim unused chunks
• Hardware limits – Upgrade RAM or CPU

Memory Problems

Symptoms: Increasing RAM usage, eventual crash

Solutions:

• Schedule regular restarts
• Check for memory-leaking plugins
• Allocate more RAM (but not too much)
• Use appropriate garbage collection flags

Recommended JVM Arguments

java -Xmx8G -Xms4G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -jar server.jar

Plugin/Mod Issues

Plugin Won’t Load

Check:

• Plugin is compatible with your server version
• All dependencies are installed
• Plugin file is in correct folder
• Check server console for specific error

Plugin Conflicts

Solutions:

• Disable plugins one by one to identify conflict
• Check plugin documentation for known conflicts
• Update all plugins to latest versions
• Contact plugin developers

Mod Content Not Loading

Solutions:

• Verify mod files are in correct location
• Check for mod compatibility issues
• Review server logs for errors
• Restart server after adding mods

World and Save Issues

World Corruption

Prevention:

• Regular backups (automated daily)
• Graceful server shutdowns (don’t force-kill)
• Use reliable storage (NVMe SSD)

Recovery:

• Restore from latest backup
• Use world repair tools (if available)
• Regenerate corrupted chunks

Backup Your Server

What to backup:

• /world/ – World data
• /plugins/ – Plugins and configs
• /mods/ – Server mods
• Configuration files

Console Commands for Troubleshooting

Common Diagnostic Commands

# Check server TPS (ticks per second)
tps

# List online players
list

# Check memory usage
mem

# Stop server gracefully
stop

# Reload configuration
reload

Log Files

Finding Logs

Server logs are typically in:

/hytale-server/logs/latest.log

Reading Error Messages

• Look for ERROR or FATAL lines
• Note the timestamp of issues
• Check stack traces for plugin names
• Search error messages online

Getting Help

Information to Gather

When asking for help, provide:

• Server version and platform
• Full error message/stack trace
• Steps to reproduce the issue
• List of installed plugins/mods
• Recent changes made
• Relevant log sections

Support Resources

• XGamingServer Support – 24/7 for hosted customers
• Hytale Forums – Community help
• Discord Servers – Real-time assistance
• Reddit – r/Hytale community