Hytale Server Not Starting or Not Connecting

Diagnose Hytale authentication, Java, version, UDP port, firewall, configuration, mod, memory, and world-loading problems.

Last updated: 2026-08-01

Start with the server console and logs/. Do not change the router until the server starts cleanly, authenticates, and accepts a connection from the host or local network.

Fast diagnostic order

  1. Check Java. Run java --version and confirm Java 25.
  2. Read the first error. Later failures are often consequences of the first authentication, asset, mod, or configuration error.
  3. Confirm authentication. Use /auth login device when the server has not completed its device flow.
  4. Match client and server versions. Hytale currently rejects connections when protocol hashes differ.
  5. Test without mods. Move unverified mods aside and retry with a clean mods/ directory.
  6. Test locally. Prove the process works before diagnosing internet reachability.
  7. Check UDP networking. The default game port is UDP 5520, not TCP.

Server starts but players cannot connect

  • Confirm the bind address and port. The default is 0.0.0.0:5520.
  • Allow the selected UDP port through the host firewall.
  • Forward that same UDP port to the server's stable local address.
  • Test from a genuinely external network; a router without NAT loopback may reject its own public address internally.
  • Compare the router WAN address with the public address. If they differ, the ISP may use carrier-grade NAT.
  • Avoid disabling the firewall or exposing the entire host through a DMZ.

Authentication fails

Run /auth login device and complete the flow through the official account URL printed by the server. Device codes expire, so restart the flow when necessary.

Protect auth.enc, auth.key, OAuth tokens, session tokens, and identity tokens. Do not paste them into issue reports or configuration tools.

Client reports a version or protocol mismatch

Update the server and assets to the same patchline and protocol version as the client. Useful update commands include:

/update check
/update download
/update apply --confirm
/update status

Release and pre-release installations should use separate directories and backups. A pre-release world or mod may not safely roll back to the release build.

Server fails after configuration changes

  • Stop the server before editing config.json, permissions.json, or world configuration.
  • Validate JSON syntax and restore the last known-good copy.
  • Remember that in-game actions can write configuration; manual changes made while running may be overwritten.
  • Keep authentication files out of any public diff or support bundle.

High memory use, pauses, or slow world loading

View distance is a major RAM driver, while high player and entity counts increase CPU load. The official manual recommends a maximum view distance of 12 chunks, or 384 blocks, as a practical performance target.

Record CPU, memory, player count, loaded areas, and installed mods before changing several settings at once. Use an explicit Java -Xmx limit appropriate for the host, but do not set it so high that the operating system has no memory left.

Still stuck?

Collect the first relevant error, server and client versions, patchline, Java version, operating system, launch command with secrets removed, and whether local and external tests differ. Compare them with the official Hytale Server Manual, then submit a redacted report through the contact page.

Next: Backups and migration.

Related pages