Troubleshooting

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:

   • KyuubiSoft Discord
   • Share logs and system info
   • Describe steps to reproduce

4. GitHub Issues:

   • Open an Issue
   • Include reproduction steps
   • Attach relevant logs