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-serverCommon 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 -dAuthentication Issues
No Device Code Appearing
docker compose logs | grep -i authEnsure 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 -fProfile Selection Required
# List profiles
docker exec -it hytale-server hytale auth profile list
# Select profile
docker exec -it hytale-server hytale auth profile select 1Or enable auto-selection:
environment:
AUTOSELECT_GAME_PROFILE: "true"Connection Issues
Players Can't Connect
Checklist:
- Server is running:
docker compose ps - Port is UDP:
"5520:5520/udp"(not TCP!) - Server authenticated:
hytale auth status - 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- 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: truePerformance Issues
Out of Memory
environment:
JAVA_OPTS: "-Xms6G -Xmx8G -XX:+UseG1GC"
deploy:
resources:
limits:
memory: 10GSlow Startup
- Enable AOT cache:
USE_AOT_CACHE: "true" - Use SSD storage
- First startup is slower (download + cache generation)
Server Lag
docker stats hytale-serverIncrease 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 -dData Lost After Restart
Ensure volume is defined:
volumes:
hytale-data:docker volume ls | grep hytaleUpdate 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 restartCheck Current Version
docker exec -it hytale-server hytale update checkDocker Issues
Image Build Fails
docker compose build --no-cache
# or
docker compose pullContainer Won't Stop
docker compose kill
docker compose rm -fDebugging
Access Container Shell
docker compose exec hytale-server bash
# Inside:
ls -la /server/
ps aux
hytale auth statusExport Logs
docker compose logs > hytale-debug.logWatch Real-time
docker compose logs -f --tail=100Getting Help
If still stuck:
-
Search GitHub Issues
-
Create issue with:
- Full error logs
- Your
docker-compose.yml - Docker version:
docker --version - OS and version
-
Official resources:
Next Steps
- Configuration — All settings
- CLI Reference — Command-line tools