Hytale Server Not Starting: Errors and Fixes

Java isn't version 25

The server is built for Java 25. With an older Java it won't even begin: you get an UnsupportedClassVersionError. Install Java 25 (the manual recommends Adoptium, Temurin) and check with “java --version” that it's the one being used: if you have several Javas installed, another one may be starting it.

You're starting it inside the launcher folder

Since Update 7, the server refuses to start if it would store its data inside the Hytale launcher's install folder, because every update patches or deletes it. It exits with code 11 and explains how to move it.

Copy the Server folder and Assets.zip to another folder and start it from there. There's an --allow-install-dir option to force it, accepting that you may lose the world: don't use it.

A mod made for another version

This is the most common one right after a big update: old mods fail to load. The console says which one. Remove the last one you added, or take them all out of the mods folder and put them back one by one, restarting each time. Before adding one, check that it supports your version (how, in the mods guide).

Early plugins, on top of that, only load if the server starts with --accept-early-plugins.

config.json has an error

If you edited it by hand, one extra comma or an unclosed quote is enough for it to fail to read the configuration. Undo your last change or run the file through a JSON validator. What each option does is in config.json option by option.

Before Update 7, a view distance (MaxViewRadius) outside 1 to 32 also stopped it from starting. Since Update 7 it adjusts it by itself with a warning.

It runs out of memory

If the console shows OutOfMemoryError, or the server stutters with very high CPU, it's short of memory: the manual warns that in Java, lack of memory shows up first as more CPU.

With the official launcher, memory is set in a jvm.options file next to start.sh, one argument per line: for example -Xmx4G for 4 GB. Don't give it more than the RAM you have free. And lower the view distance: it's what uses the most memory (how much RAM you need).

It crashes right after updating

The official launcher warns you if the server crashes within 30 seconds of applying an update. Your previous files are kept in updater/backup/: to roll back, delete Server/ and Assets.zip and put the ones from updater/backup/ in their place.

Careful: on the previous version, players who have already updated can't join. Rolling back is for saving the world, not for carrying on playing. Usually the cause is a mod: try without them first.

It starts, but isn't linked

If you see “No server tokens configured” or “Token validation failed. Server starting unauthenticated.”, the server is running but won't accept players: it isn't linked to a Hytale account. Link it with “auth login device” (the guide to linking a Hytale server to your account explains it). If it's linked and still nobody can join, carry on with can't connect to my Hytale server.

The port is already in use

If another server or program is already using UDP 5520, this one can't listen on it. Close the other one or start with another port: --bind 0.0.0.0:5521, for example. Remember to open the new one in the firewall and on the router, as UDP.

On NapNodes

Java 25, the folder structure and the memory are already set up: the server's memory is written again on every start, including when you change its RAM with “Adjust” in “My servers”. So if yours won't start, check “Console”: it's almost always a mod or a config.json edited by hand.

If the console shows a “[NapNodes]” line saying the game hasn't been downloaded yet and to start the server again to request a new code (for now that line is in Spanish), the server never got linked: click “Start” and confirm the code on the card in time.

On the free server, the disk is 15 GB: the game takes about 3 GB and each update downloads about as much again before it's applied. We email you at 80 % and at 95 %; if it fills up, the game can't save. Free up space in “Files” (check Server/backups too, Hytale's own backups) or move to a plan.

If you can't see the cause, copy the last lines of the console and open a ticket in “Help”.

Frequently asked questions