Troubleshooting

Common issues and solutions for Hytale Docker

Troubleshooting

Solutions to common issues running your Hytale server.

Server Won't Start

Container Exits Immediately

docker compose logs hytale-server

Common causes:

  • Java version mismatch (image includes Java 25+)
  • Download failed due to network or auth issues
  • Missing hytale-downloader

Download Fails

# Check network
docker compose exec hytale-server ping -c 4 google.com

# Force re-download
docker compose down
FORCE_UPDATE=true docker compose up -d

Authentication Issues

No Device Code Appearing

docker compose logs | grep -i auth

Ensure the container has network access to Hytale OAuth servers.

Re-auth Required Every Restart

Tokens are stored in /server/.hytale/tokens/ in the volume.

# Check token status
docker exec -it hytale-server hytale auth status

# Verify files exist
docker exec hytale-server ls -la /server/.hytale/tokens/

Device Code Expired

Device codes are valid for 15 minutes. Restart to get a new code:

docker compose restart
docker compose logs -f

Profile Selection Required

# List profiles
docker exec -it hytale-server hytale auth profile list

# Select profile
docker exec -it hytale-server hytale auth profile select 1

Or enable auto-selection:

environment:
  AUTOSELECT_GAME_PROFILE: "true"

Connection Issues

Players Can't Connect

Checklist:

  1. Server is running: docker compose ps
  2. Port is UDP: "5520:5520/udp" (not TCP!)
  3. Server authenticated: hytale auth status
  4. Firewall allows UDP 5520
# Linux
sudo ufw allow 5520/udp

# Windows
netsh advfirewall firewall add rule name="Hytale" dir=in action=allow protocol=UDP localport=5520
  1. Router port forwarding configured for UDP

Connection Timeout

  • Firewall blocking UDP
  • Wrong protocol (TCP instead of UDP)
  • Router not forwarding
  • ISP blocking UDP

Test order: localhost → LAN IP → public IP


Command Issues

Commands Not Working

# Check server is running
docker compose ps

# Check logs
docker compose logs --tail=50

# Ensure stdin/tty enabled
# docker-compose.yml:
#   stdin_open: true
#   tty: true

Performance Issues

Out of Memory

environment:
  JAVA_OPTS: "-Xms6G -Xmx8G -XX:+UseG1GC"

deploy:
  resources:
    limits:
      memory: 10G

Slow Startup

  1. Enable AOT cache: USE_AOT_CACHE: "true"
  2. Use SSD storage
  3. First startup is slower (download + cache generation)

Server Lag

docker stats hytale-server

Increase memory or check host resources.


Volume Issues

Permission Denied

docker compose down

# Find volume path
docker volume inspect hytale-docker_hytale-data | grep Mountpoint

# Fix ownership (container runs as UID 1000)
sudo chown -R 1000:1000 /path/to/volume

docker compose up -d

Data Lost After Restart

Ensure volume is defined:

volumes:
  hytale-data:
docker volume ls | grep hytale

Update Issues

Server Won't Update

# Force update
docker compose down
FORCE_UPDATE=true docker compose up -d

# Or schedule manually
docker exec -it hytale-server hytale update schedule
docker compose restart

Check Current Version

docker exec -it hytale-server hytale update check

Docker Issues

Image Build Fails

docker compose build --no-cache
# or
docker compose pull

Container Won't Stop

docker compose kill
docker compose rm -f

Debugging

Access Container Shell

docker compose exec hytale-server bash

# Inside:
ls -la /server/
ps aux
hytale auth status

Export Logs

docker compose logs > hytale-debug.log

Watch Real-time

docker compose logs -f --tail=100

Getting Help

If still stuck:

  1. Search GitHub Issues

  2. Create issue with:

    • Full error logs
    • Your docker-compose.yml
    • Docker version: docker --version
    • OS and version
  3. Official resources:

Next Steps

On this page