# Troubleshooting

# Troubleshooting

Solutions for common issues with the KyuubiSoft Panel.

## Installation Issues

### Docker Compose Fails

**Error:** `docker-compose: command not found`

**Solution:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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:
   ```bash
   docker-compose logs hytale
   ```
2. Verify server files exist:
   ```bash
   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**
   ```bash
   # 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**
   ```bash
   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**
   ```bash
   docker-compose ps
   docker-compose up -d hytale
   ```

2. **Network issues**
   ```bash
   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:**
```bash
df -h /opt/hytale/backups
```

**Permissions:**
```bash
sudo chmod 777 /opt/hytale/backups
```

### Restore Fails

**File Integrity:**
```bash
# Test archive
tar -tzf /opt/hytale/backups/backup.tar.gz
```

**Space:**
```bash
# 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:**
```bash
# In .env
TRUST_PROXY=true
CORS_ORIGINS=https://your-domain.com
```

**Nginx WebSocket:**
```nginx
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:**
```bash
# 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:**
```bash
# Extract specific file
tar -xzf backup.tar.gz data/config.json
```

## Getting Help

If you can't resolve an issue:

1. **Check Logs:**
   ```bash
   docker-compose logs --tail=100 hytale
   docker-compose logs --tail=100 hytale-manager
   ```

2. **Collect System Info:**
   ```bash
   docker --version
   docker-compose --version
   uname -a
   free -h
   ```

3. **Join Discord:**
   - [KyuubiSoft Discord](https://dc.gg/kyuubisoft)
   - Share logs and system info
   - Describe steps to reproduce

4. **GitHub Issues:**
   - [Open an Issue](https://github.com/KyuubiDDragon/KyuubiSoft-Hytale-Panel/issues)
   - Include reproduction steps
   - Attach relevant logs