Hytale Connection Troubleshooting Guide

Experiencing connection issues with Hytale? This comprehensive guide covers common networking problems and their solutions, from basic diagnostics to advanced troubleshooting techniques.

Quick Navigation

Common Connection Issues

"Share Code Not Working"

Symptoms: Friend enters your share code but connection fails or times out.

Common Causes:

  • UPnP is disabled on your router
  • You're behind CGNAT (Carrier-Grade NAT)
  • Strict firewall blocking QUIC/UDP traffic
  • Both players behind incompatible NATs

Solutions:

  1. Enable UPnP in your router settings (usually under "Advanced" or "WAN Settings")
  2. Manually port forward UDP port 5520 to your local IP address
  3. Check if you have CGNAT by visiting whatismyip.com and comparing it to your router's WAN IP
  4. If you have CGNAT, use Tailscale VPN or rent a dedicated server
  5. Have your friend host instead (role reversal)

"Can't Connect to Dedicated Server"

Symptoms: Connection times out when trying to join a dedicated server by IP.

Common Causes:

  • Server not actually running or crashed
  • Port 5520 not open on server firewall
  • Wrong IP address or port being used
  • Server authentication not configured
  • Cloud firewall/security group blocking traffic

Solutions:

  1. Verify server is running by checking the console for "Server listening on port 5520"
  2. Test from the server itself using localhost connection
  3. Check firewall rules (see Firewall Configuration section)
  4. Verify authentication is set up correctly (see Server Authentication Guide)
  5. If using cloud hosting, check security group/firewall rules allow UDP port 5520

"Connection Drops After a Few Minutes"

Symptoms: Can connect initially but get disconnected after 5-10 minutes.

Common Causes:

  • NAT timeout on router (typically 5-15 minutes)
  • Unstable internet connection
  • Server resource issues (RAM, CPU spikes)
  • Keep-alive packets not being sent

Solutions:

  1. Increase NAT timeout in router settings (if available)
  2. Ensure stable connection - test with ping to 8.8.8.8 for packet loss
  3. Monitor server resources - check RAM usage and CPU load
  4. Use a wired Ethernet connection instead of WiFi when possible
  5. Consider using Tailscale for more reliable connections

"High Latency / Lag"

Symptoms: Connected but experiencing significant lag (200+ ms ping).

Common Causes:

  • Geographic distance between players
  • Connection being routed through relay servers
  • Network congestion or ISP throttling
  • Server performance issues

Solutions:

  1. Use a dedicated server in a location central to all players
  2. Check if your connection is direct or relayed (Tailscale shows this)
  3. Close bandwidth-heavy applications (streaming, downloads)
  4. Reduce server view distance to decrease data transfer
  5. Use QoS (Quality of Service) settings on your router to prioritize gaming traffic

Diagnostic Tools & Testing

1. Port Checking Tools

Verify that your ports are properly open and accessible from the internet:

Important: Your Hytale server MUST be running when testing ports!

Most online port checkers don't support UDP testing. For accurate UDP testing, have a friend attempt to connect.

2. Network Diagnostics (Command Line)

Use these commands to diagnose network issues:

Test Connection to Server:

# Windows

ping server-ip-address

# Linux/macOS

ping -c 10 server-ip-address

Trace Network Route:

# Windows

tracert server-ip-address

# Linux/macOS

traceroute server-ip-address

Check Open Ports on Your Machine:

# Windows

netstat -an | findstr 5520

# Linux/macOS

netstat -an | grep 5520

# Or use ss on Linux

ss -ulpn | grep 5520

Check Your Public IP:

# Windows PowerShell

(Invoke-WebRequest -Uri "https://api.ipify.org").Content

# Linux/macOS

curl https://api.ipify.org

3. CGNAT Detection

Check if you're behind Carrier-Grade NAT:

  1. Get your router's WAN IP address (usually in router admin panel under Status or WAN settings)
  2. Compare it to your public IP from whatismyip.com
  3. If the IPs don't match AND your router's WAN IP starts with 100.64.x.x, you have CGNAT
  4. CGNAT means port forwarding won't work - you'll need Tailscale or a dedicated server

4. UPnP Testing

Verify if UPnP is working properly:

  • Check router admin panel - look for UPnP under "Advanced Settings"
  • Look for UPnP status page showing active port mappings
  • You should see port 5520 listed when Hytale is running
  • If UPnP isn't available or working, manually port forward instead

Firewall Configuration

Properly configure your firewall to allow Hytale traffic on UDP port 5520.

Windows Firewall

  1. Open Windows Defender Firewall with Advanced Security
  2. Click "Inbound Rules" in the left panel
  3. Click "New Rule..." in the right panel
  4. Select "Port" and click Next
  5. Select "UDP" and enter "5520" as the port
  6. Select "Allow the connection"
  7. Apply to all profiles (Domain, Private, Public)
  8. Name it "Hytale Server" and finish

PowerShell Command (Admin):

New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow

Linux Firewall (UFW)

Ubuntu/Debian systems using UFW:

# Allow Hytale port

sudo ufw allow 5520/udp

# Enable firewall if not already enabled

sudo ufw enable

# Check status

sudo ufw status

Linux Firewall (firewalld)

RHEL/CentOS/Fedora systems using firewalld:

# Add Hytale port

sudo firewall-cmd --permanent --add-port=5520/udp

# Reload firewall

sudo firewall-cmd --reload

# Verify

sudo firewall-cmd --list-ports

Linux Firewall (iptables)

Manual iptables configuration:

# Allow incoming UDP on port 5520

sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT

# Save rules (Ubuntu/Debian)

sudo netfilter-persistent save

# Or for RHEL/CentOS

sudo service iptables save

macOS Firewall

  1. Open System Settings
  2. Go to Network → Firewall
  3. Click "Options..."
  4. Click the "+" button
  5. Browse to your Hytale server executable
  6. Select "Allow incoming connections"
  7. Click OK

Note: macOS firewall is application-based, not port-based. Adding the Hytale server application will automatically allow its network traffic.

Cloud Provider Firewalls

If hosting on cloud platforms, configure security groups:

AWS EC2:

  • Edit Security Group
  • Add Inbound Rule: Custom UDP, Port 5520, Source 0.0.0.0/0

Google Cloud:

  • VPC Network → Firewall
  • Create rule: Ingress, UDP:5520, Source ranges: 0.0.0.0/0

Azure:

  • Network Security Group
  • Add Inbound Rule: UDP, Port 5520, Source: Any

DigitalOcean:

  • Networking → Firewalls
  • Add Inbound Rule: Custom, UDP, 5520, All IPv4

Router & Port Forwarding Issues

Port Forwarding Basics

Port forwarding redirects incoming traffic from your router to a specific device on your local network.

Required Information:

  • External Port: 5520 (UDP)
  • Internal Port: 5520 (UDP)
  • Protocol: UDP (NOT TCP!)
  • Internal IP: Your computer's local IP (e.g., 192.168.1.100)

Finding Your Local IP Address

# Windows

ipconfig

# Look for "IPv4 Address"

# Linux/macOS

ip addr show

# Or

ifconfig

Common Port Forwarding Mistakes

❌ Mistake: Forwarding TCP instead of UDP

Hytale uses the QUIC protocol which runs over UDP, not TCP. Make sure you select UDP when creating the port forwarding rule!

❌ Mistake: Dynamic IP address

If your local IP changes (DHCP), port forwarding will stop working.

✓ Solution: Set a static IP or use DHCP reservation in your router

❌ Mistake: Multiple routers (Double NAT)

If you have two routers (e.g., ISP modem/router + your own router), you need to port forward on BOTH devices.

✓ Solution: Put your router in bridge mode, or forward ports on both devices

❌ Mistake: Forgetting to save/apply changes

Many routers require clicking "Save" AND "Apply" or rebooting for changes to take effect.

✓ Solution: Always save changes and reboot router if needed

Testing Port Forwarding

  1. Ensure your Hytale server is running
  2. Get your public IP from whatismyip.com
  3. Have a friend try to connect using your public IP
  4. Check your server console logs for connection attempts
  5. If it fails, verify firewall rules and router configuration

Router-Specific Issues

ISP Router Limitations:

Some ISP-provided routers have limited port forwarding capabilities or block certain ports. Consider using your own router if possible.

Port Triggering vs Port Forwarding:

Use Port Forwarding (permanent), not Port Triggering (temporary). They are different features!

DMZ (Demilitarized Zone):

As a last resort, you can place your server in the DMZ (router settings). This forwards ALL ports to that device. Only use this if port forwarding doesn't work.

NAT & CGNAT Problems

What is NAT?

NAT (Network Address Translation) allows multiple devices on your home network to share a single public IP address. Your router performs NAT to route traffic between your devices and the internet.

Types of NAT:

  • Full Cone NAT: Best for gaming - allows any external host to connect once a port mapping exists
  • Restricted Cone NAT: Moderate - allows connections only from IPs you've communicated with
  • Port Restricted Cone NAT: Strict - requires both IP and port to match previous communication
  • Symmetric NAT: Most restrictive - peer-to-peer connections extremely difficult

What is CGNAT?

CGNAT (Carrier-Grade NAT) is an additional layer of NAT performed by your Internet Service Provider. With CGNAT:

  • You don't have a truly "public" IP address
  • Port forwarding on your router doesn't work
  • Incoming connections are blocked at the ISP level
  • Share codes and hosting become impossible

⚠️ CGNAT Detection

If your router's WAN IP starts with 100.64.x.x (the CGNAT IP range), you are behind CGNAT and port forwarding will NOT work.

Solutions for CGNAT

1. Request a Public IP from Your ISP

Some ISPs will give you a public IP address if you ask (may cost extra $5-10/month).

  • Call your ISP support
  • Ask for "a public IP address" or "to be removed from CGNAT"
  • Explain you need it for self-hosting / gaming

2. Use Tailscale VPN (Recommended)

Tailscale creates a virtual private network that bypasses NAT entirely. See our Tailscale Setup Guide.

  • Free for personal use
  • Works behind any NAT type
  • Simple setup for you and friends
  • Encrypted connections

3. Rent a Dedicated Server

Host your Hytale server on a cloud provider or game server host. Browse hosting options.

  • No NAT/firewall issues
  • 24/7 uptime
  • Better performance
  • Starting at $4.99/month

4. IPv6 Workaround

If your ISP provides IPv6, CGNAT may not apply to IPv6 addresses.

  • Check if you have IPv6 connectivity
  • Both host and players need IPv6
  • Use IPv6 address for connections
  • Limited compatibility with some networks

Dedicated Server Issues

Server Won't Start

Issue: "Port already in use"

Another process is using port 5520.

Solution:

# Windows: Find process using port 5520

netstat -ano | findstr :5520

# Kill process by PID

taskkill /PID [PID_NUMBER] /F

# Linux: Find and kill process

sudo lsof -i :5520

sudo kill -9 [PID]

Issue: "Permission denied"

Server doesn't have permission to bind to port 5520.

Solution (Linux): Run with sudo OR use setcap to allow non-root binding:

sudo setcap 'cap_net_bind_service=+ep' /path/to/hytale-server

Issue: "Out of memory" / OOM errors

Server doesn't have enough RAM allocated.

Solution: Increase RAM allocation in launch command:

java -Xmx4G -Xms4G -jar hytale-server.jar

Authentication Issues

Players can't join due to authentication failures:

  • Verify server authentication is properly configured (see Server Authentication Guide)
  • Check server logs for specific authentication errors
  • Ensure players are using valid Hytale accounts (not cracked)
  • Verify OAuth2 credentials are valid and not expired
  • Check that authentication servers are reachable

Performance Issues

Server running slowly or experiencing lag:

  • Check RAM usage - allocate more if constantly at 90%+
  • Monitor CPU usage - ensure not hitting 100% constantly
  • Reduce view distance in server configuration
  • Install performance optimization plugins
  • Check disk I/O - use SSD storage for best performance
  • Review server logs for errors or warnings
  • Ensure AOT cache is properly generated (first startup takes longer)

World Corruption / Won't Load

Server crashes when loading world or reports corruption:

  1. Stop the server immediately to prevent further corruption
  2. Check logs for specific error messages about which chunk/region failed
  3. Restore from backup if available (always keep backups!)
  4. If no backup, try deleting just the corrupted region file (if identified)
  5. As last resort, use world repair tools if available in future Hytale updates

💡 Prevention is Key

Set up automatic backups! Schedule daily backups of your world folder to prevent data loss. Consider using tools like rsync, rclone, or Windows Task Scheduler.

Plugin/Mod Conflicts

Server crashes or behaves strangely after installing plugins:

  1. Check server logs for plugin-related errors
  2. Verify plugin compatibility with your server version
  3. Remove recently added plugins one by one to isolate issue
  4. Check for dependency conflicts between plugins
  5. Ensure plugins are from trusted sources (official Hytale repositories)
  6. Update plugins to latest compatible versions

Advanced Troubleshooting

Packet Capture Analysis

Use Wireshark to analyze network traffic and diagnose connection issues:

  1. Download and install Wireshark
  2. Start capturing on your network interface
  3. Filter for UDP port 5520: udp.port == 5520
  4. Attempt to connect to the server
  5. Look for QUIC packets - you should see handshake attempts
  6. If no packets appear, firewall is blocking before network layer
  7. If packets sent but no response, issue is at server/router level

MTU Issues

Maximum Transmission Unit problems can cause packet fragmentation:

Symptoms of MTU Issues:

  • Connection succeeds but immediately drops
  • Can connect locally but not over internet
  • Random disconnects during gameplay

Testing MTU:

# Windows (find optimal MTU)

ping -f -l 1472 server-ip-address

# Decrease 1472 until ping succeeds

# Linux/macOS

ping -M do -s 1472 server-ip-address

If you need to reduce MTU, configure it in your network adapter settings (Windows) or using ip link (Linux).

ISP Traffic Shaping / Throttling

Some ISPs throttle or deprioritize gaming traffic:

Symptoms:

  • Consistent lag during peak hours (6-10 PM)
  • Good ping to other services but bad to game servers
  • Download speed tests show good results but gameplay lags

Testing:

Run speed tests during different times of day. Compare results with dedicated gaming ping tests.

Solutions:

  • Use a VPN to encrypt traffic (prevents deep packet inspection)
  • Upgrade to business/gaming ISP tier if available
  • File complaint with ISP about throttling
  • Consider switching ISPs if throttling is severe

DNS Issues

While Hytale uses direct IP connections, DNS can affect authentication:

Try Alternative DNS Servers:

  • Cloudflare: 1.1.1.1, 1.0.0.1
  • Google: 8.8.8.8, 8.8.4.4
  • Quad9: 9.9.9.9, 149.112.112.112

Change DNS in your network adapter settings or router configuration.

Reading Server Logs

Server logs contain valuable troubleshooting information. See our Log Files Guide for detailed analysis instructions.

Key Log Locations:

  • logs/latest.log - Current session
  • logs/YYYY-MM-DD-N.log.gz - Historical logs
  • crash-reports/ - Crash dumps

Frequently Asked Questions

Why does Hytale use UDP instead of TCP?

Hytale uses the QUIC protocol which runs over UDP. QUIC provides better performance for real-time gaming with lower latency, faster connection establishment, and improved handling of packet loss compared to traditional TCP.

Can I use a different port instead of 5520?

Currently, Hytale servers are hardcoded to use port 5520. Future updates may allow custom ports, but for now you must use 5520 or your server won't be accessible.

How do I know if my router supports UPnP?

Check your router's admin panel (usually under Advanced Settings or WAN Configuration). Look for "UPnP" or "Universal Plug and Play" option. Most modern routers support UPnP, though it may be disabled by default.

Enable it, save settings, and reboot your router. Then try using share codes again.

What's the difference between share codes and direct IP connection?

Share codes: Temporary codes for peer-to-peer connections. They use UPnP to automatically handle port forwarding and include connection candidates (your public IP, local IP, and relay options).

Direct IP: Used for dedicated servers. Players manually enter your public IP address. Requires manual port forwarding or firewall configuration.

Should I use Windows Firewall if I have a hardware firewall?

Yes! Hardware firewalls (router) and software firewalls (Windows Firewall, Linux iptables) serve different purposes. The hardware firewall protects your entire network, while the software firewall protects the individual device. Both need to be configured to allow Hytale traffic.

My connection worked yesterday but doesn't work today. Why?

Common reasons for suddenly broken connections:

  • Your public IP address changed (dynamic IP)
  • Router was rebooted and lost UPnP mappings
  • Windows/Linux update reset firewall rules
  • Your local IP changed due to DHCP
  • ISP maintenance or routing changes

Can I host multiple Hytale servers on the same machine?

Currently, Hytale servers use a fixed port (5520), so you can only run one server per machine/IP address. Future updates may support custom ports or multiple instances. For now, use separate VMs, containers, or physical machines for multiple servers.

What's the best way to host Hytale for friends long-term?

For casual play with 2-5 friends, use Tailscale - it's free and bypasses all NAT issues.

For larger groups (6+ players) or public servers, rent a dedicated Hytale server. It provides better performance, 24/7 uptime, and no networking headaches.

Related Guides

Playing with Friends

Learn how to use share codes and host multiplayer games

Tailscale Setup

Use VPN to bypass NAT and CGNAT issues

Server Manual

Complete guide to setting up a Hytale dedicated server

Hytale Server Hosting

Skip the hassle - rent a pre-configured server

Still Having Connection Issues?

Consider using our managed Hytale server hosting. No port forwarding, no firewall configuration, no NAT problems. Just instant, reliable Hytale servers.

View Hosting Plans →