Skip to main content

Troubleshooting

Solutions for common issues with the KyuubiSoft Panel.

Installation Issues​

Docker Compose Fails​

Error: docker-compose: command not found

Solution:

# Install Docker Compose plugin
sudo apt install docker-compose-plugin

# Use new syntax
docker compose up -d

Permission Denied​

Error: Permission denied when starting containers

Solution:

# Fix ownership (UID 9999 is the container user)
sudo chown -R 9999:9999 /opt/hytale
sudo chmod -R g+rw /opt/hytale

Port Already in Use​

Error: Bind for 0.0.0.0:18080 failed: port is already allocated

Solution:

# Find what's using the port
sudo lsof -i :18080

# Change port in .env
MANAGER_PORT=18081

Server Issues​

Server Won't Start​

Symptoms: Container starts but server doesn't run

Checklist:

  1. Check server logs: 
    docker-compose logs hytale
  2. Verify server files exist: 
    docker exec hytale ls -la /opt/hytale/server/
  3. Check Java heap settings match available RAM
  4. Verify Assets.zip is extracted

Server Crashes on Start​

Common Causes:

  1. Out of Memory

    # Increase RAM in .env
    JAVA_MAX_RAM=6G
    DOCKER_MEMORY_LIMIT=8G

  2. Corrupted World

    • Restore from backup
    • Or delete world folder to regenerate

  3. Bad Plugin

    • Remove recently added plugins
    • Check plugin compatibility

Can't Connect to Server​

Checklist:

  1. Port Forwarding

    • UDP port 5520 must be open
    • Check router/firewall settings

  2. Server Authentication

    docker attach hytale
    /auth status

  3. Network Mode

    • Check AUTH_MODE in .env
    • Use offline for LAN only

Panel Issues​

Can't Login to Panel​

Wrong Credentials:

  • Check MANAGER_USERNAME and MANAGER_PASSWORD in .env
  • Passwords are case-sensitive

JWT Errors:

  • Regenerate JWT_SECRET
  • Clear browser cookies
  • Restart manager container

Panel Shows "Disconnected"​

Causes:

  1. Server container not running

    docker-compose ps
    docker-compose up -d hytale

  2. Network issues

    docker network inspect hytale-net

  3. CORS misconfiguration

    • Check CORS_ORIGINS matches your access URL
    • Include protocol: http:// or https://

Console Not Updating​

Solutions:

  1. Clear browser cache
  2. Check WebSocket connection (F12 → Network → WS)
  3. Restart manager container
  4. Verify TRUST_PROXY if behind reverse proxy

Performance Page Empty​

KyuubiAPI Plugin Required:

  1. Go to Settings → KyuubiAPI
  2. Install the plugin
  3. Restart server
  4. Verify plugin status shows "Connected"

Backup Issues​

Backup Fails​

Disk Space:

df -h /opt/hytale/backups

Permissions:

sudo chmod 777 /opt/hytale/backups

Restore Fails​

File Integrity:

# Test archive
tar -tzf /opt/hytale/backups/backup.tar.gz

Space:

# Check data directory space
df -h /opt/hytale/data

Mod Issues​

Mod Won't Load​

  1. Check Hytale version compatibility
  2. Look for errors in console
  3. Verify mod file isn't corrupted
  4. Check for missing dependencies

CurseForge Not Working​

No Results:

  • Check internet connectivity
  • CurseForge may be rate limiting
  • Try setting CURSEFORGE_API_KEY

Download Fails:

  • Some mods don't allow 3rd party downloads
  • Try manual download and upload

Plugin Conflicts​

Symptoms: Server crashes or features don't work

Solution:

  1. Disable all plugins
  2. Enable one at a time
  3. Test after each enable
  4. Identify conflicting plugin

Network Issues​

Behind Reverse Proxy​

Configuration:

# In .env
TRUST_PROXY=true
CORS_ORIGINS=https://your-domain.com

Nginx WebSocket:

location /api/console/ws {
    proxy_pass http://localhost:18080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

HTTPS Not Working​

  1. Verify SSL certificate
  2. Check reverse proxy config
  3. Ensure TRUST_PROXY=true
  4. Update CORS_ORIGINS to https

Database/Data Issues​

Corrupted User Data​

Reset Users:

# Backup first
docker exec hytale-manager cp /app/data/users.json /app/data/users.json.bak

# Remove to reset
docker exec hytale-manager rm /app/data/users.json
docker-compose restart hytale-manager

Lost Configuration​

Restore from Backup:

# Extract specific file
tar -xzf backup.tar.gz data/config.json

Getting Help​

If you can't resolve an issue:

  1. Check Logs:

    docker-compose logs --tail=100 hytale
    docker-compose logs --tail=100 hytale-manager

  2. Collect System Info:

    docker --version
    docker-compose --version
    uname -a
    free -h

  3. Join Discord:

  4. GitHub Issues: