Hytale Server Troubleshooting Guide
Solutions for the most common Hytale dedicated server issues including connection failures, startup errors, and authentication problems.
Hytale Server Troubleshooting Guide
This guide covers the most common issues encountered when running a Hytale dedicated server, organized by symptom.
Server Won't Start
Java Version Mismatch
Symptom: Server exits immediately with an error like:
Error: LinkageError occurred while loading main class com.hytale.server.Main
UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime
Cause: Hytale requires Java 25. Earlier Java versions cannot load the server binary.
Fix:
java -version
If this does not report Java 25 or higher, install the correct version:
sudo apt install -y openjdk-25-jre-headless
If multiple Java versions are installed, set the correct one as default:
sudo update-alternatives --config java
Missing or Corrupted Server Files
Symptom: FileNotFoundException or ClassNotFoundException on startup.
Fix: Re-run the Hytale Downloader CLI to re-download the server files:
./hytale-downloader download --type server --output /opt/hytale-server
Players Get "Connection Timed Out"
Cause: UDP port 5520 is not open. Hytale uses the QUIC protocol over UDP exclusively. Opening TCP 5520 has no effect.
Fix — Linux UFW:
sudo ufw allow 5520/udp
sudo ufw reload
Fix — iptables:
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT
Fix — cloud security group: Add a UDP inbound rule for port 5520 in your provider's firewall console.
Verify the server is listening:
sudo ss -ulnp | grep 5520
See Hytale Server Port Configuration for full instructions.
OAuth2 / Authentication Errors
"Token expired" or "Authentication required"
Cause: The OAuth2 session issued by the Hytale Downloader CLI expires after 1 hour of inactivity. This affects the download tool and, in some configurations, the server's initial auth check on startup.
Fix:
./hytale-downloader auth --refresh
If the refresh fails, run the full auth flow again:
./hytale-downloader auth
Server Fails Auth Check on Restart
If the server was stopped for more than an hour and fails to start due to an auth error, re-authenticate before starting:
./hytale-downloader auth --refresh
sudo systemctl start hytale
Server Starts but Players Can't Connect
Whitelist Blocking Players
Symptom: Players see "You are not whitelisted on this server."
Fix: Either add the player to whitelist.json or disable the whitelist in config.json:
{ "whitelist": false }
See Using the Hytale Server Whitelist.
Session Limit Reached
Symptom: Players cannot join despite available slots on the server.
Cause: The Hytale account running the server has hit its 100-session cap across all servers.
Fix: Wait for players to disconnect to free sessions, or review your server's maxPlayers setting to prevent future oversubscription. See Understanding Hytale Session Limits.
High Latency / Lag
Server Tick Overruns
Symptom: Log messages like "Server is running behind by Xms — skipping Y ticks."
Fix:
- Reduce
viewDistanceinconfig.json(try6or8) - Increase
-Xmxif RAM is constrained - Remove or replace heavy plugins
- Upgrade server hardware
See Hytale Server Performance Optimization for a full checklist.
World Not Loading / Missing
Symptom: Server starts but a world is missing or freshly generated unexpectedly.
Cause: The world directory under universe/worlds/ was deleted, moved, or its config.json is malformed.
Fix:
- Check that the world directory exists:
ls /opt/hytale-server/universe/worlds/ - Validate its
config.jsonis valid JSON:python3 -m json.tool /opt/hytale-server/universe/worlds/overworld/config.json - Restore from backup if the directory is missing.
Config Changes Not Taking Effect
Symptom: Edits to config.json or permissions.json are not reflected in the running server.
Fix: Most configuration changes require a full server restart:
sudo systemctl restart hytale
Useful Log Commands
# Follow live server logs
sudo journalctl -u hytale -f
# Show the last 100 lines
sudo journalctl -u hytale -n 100
# Filter for errors only
sudo journalctl -u hytale -p err -n 50