Hytale Server Troubleshooting Guide
This page helps you troubleshoot the most common issues people run into when hosting a Hytale Server. It’s written for HypeServ users, but the underlying fixes apply to Hytale servers in general.
Quick checklist (do this first)
Before digging into specific errors, please check these 5 things first:
- Restart the server
- Check the server version vs client version (Your Server version should match you local game version)
- Confirm the server is authenticated. You can check this by running:
/auth status
- (Does not apply to HypeServ customers) Check your Firewall and make sure the Game-Port is open on UDP and not TCP!
- If you installed mods recently: remove the newest mod and retry (mods are a top cause of startup crashes).
Connection and authentication problems
“Failed token authentication” / “Failed to connect” / “Invalid access token”
This usually looks like one of these patterns:
- You can play offline/singleplayer, but joining your server fails
- Errors mention token/authentication/access token (403) in the server console
- Joining works for some people but not others
On Windows:
- Open Settings → Time & language → Date & time
- Enable Set time automatically
- Click Sync now
Community reports confirmed this resolves “failed token authentication / failed to connect” immediately for some players.
A dedicated server must authenticate after first start before it can accept players.
In a standard Hytale server console you’ll see a device login prompt similar to:
- Run:
/auth login device - Open the shown URL and enter the code
- Wait for “Authentication successful”
This flow is documented in the official server manual.
During busy periods, repeatedly spamming login/token requests can make failures more likely. In community threads, people specifically call out issues triggered by multiple access-token requests during login.
If you hit token errors:
- Fully close the game and launcher
- Wait a moment (like 10-60 minutes)
- Relaunch and try again once
World not loading, very slow join, desync (Windows)
Symptoms often look like:
- Your internet is fine
- Singleplayer loads fine
- Connecting to a server is very slow, the world doesn’t load, or your friend can see you move but you can’t interact
Hytale uses the QUIC protocol for client-server traffic, and Hypixel notes that some Windows network drivers (Intel/Realtek) can have compatibility issues with QUIC.
Hypixel’s official guidance recommends testing with a USB Ethernet dongle first (to confirm it’s driver-related), then disabling specific adapter features in the NIC advanced settings.
Common toggles they mention disabling include:
- Priority & VLAN
- Receive Segment Coalescing (IPv4 / IPv6)
- Energy-efficiency related features (EEE / Green Ethernet), plus a few offload options
Follow the step-by-step instructions in the official article here and test after each change.
Because Hytale uses QUIC over UDP, your firewall and port forwarding must allow UDP on the server port (default 5520).
The official server manual explicitly calls out:
- UDP is required
- TCP forwarding is not required for Hytale server connections
- If you changed the port, forward that custom UDP port instead
Severe ping spikes / rubber-banding / short desync bursts
If gameplay “freezes” for ~10–20 seconds and then recovers, the usual suspects are:
- Network instability (local connection, Wi-Fi interference, routing)
- Server CPU stalls (a heavy moment/event that pauses simulation)
- Over-aggressive view distance / too much loaded area
The community is actively reporting this pattern during early multiplayer use.
What to try (in order):
- Test with a wired connection (or a different network).
- Reduce your server’s view distance (see our settings guide here)
- If the spikes started after adding mods, roll back the last mod change.
Version mismatch after updates
If players suddenly can’t join right after a game update, this is often the reason:
Hytale uses a protocol hash for compatibility. If the client and server protocol hashes don’t match exactly, the connection is rejected. The official manual notes that servers must update immediately after an update (at least for now).
To resolve this issue, simply:
- Restart the server so it pulls the newest build (Your HypeServ Hytale Server updates automatically for you).
- If you run custom server files, update them before allowing players to join.
- Restart your game and launcher to make sure you have the latest version installed.
Server won’t start or keeps crashing
“Server failed to boot” / stuck during startup
If the server never becomes joinable:
- Open the
Consoleand look for the first real error. - Temporarily remove all mods (move files out of
mods/) and start again. The official manual confirms mods live inmods/. - Confirm you’re not trying to run on an unsupported setup:
- Dedicated servers require Java 25.
Performance and resource problems (lag, stutters, high memory)
Lag that gets worse with more exploring or more players
The Hytale server manual gives a very practical rule: view distance is the main driver for RAM usage, and it recommends limiting maximum view distance to 12 chunks (384 blocks) for performance and gameplay.
It also explains what typically drives resource usage:
- CPU: high player counts, lots of entities (NPCs/mobs)
- RAM: large loaded area, high view distance, players exploring separately
Fixes that usually work well:
- Upgrade the amount of RAM or CPU Cores assigned to your server
- Reduce view distance first (biggest win).
- Avoid letting many players explore in opposite directions early on (it balloons loaded area).
- If you use mods, add them slowly and monitor performance after each change.
“Hosting with friends” issues (UPnP / join codes)
If you’re not using a dedicated server and instead rely on friend-join hosting, be aware:
Hytale’s friend join system depends on UPnP and direct connections, and Hypixel explicitly says it won’t work on all networks yet (this system is still maturing as Hytale is still in Early-Access).
Best fix: use a dedicated server (like our HypeServ Hytale servers) instead of friend-hosting if your network/UPnP setup is unreliable.