firefrost-operations-manual/docs/troubleshooting/hytale-troubleshooting-guide.md

# Hytale Server Troubleshooting Guide

## Common Issues & Solutions

### 1. "World default already exists on disk!" Error

**Symptoms:**
```
java.lang.IllegalArgumentException: World default already exists on disk!
at com.hypixel.hytale.server.core.universe.Universe.addWorld
```

**Cause:** Corrupted world state or plugin databases referencing old world data.

**Solution:**
```bash
# SSH to server
ssh root@<server-ip>
cd /var/lib/pterodactyl/volumes/<hytale-uuid>

# Backup universe folder first
tar -czf universe-backup-$(date +%Y%m%d-%H%M%S).tar.gz universe/

# Remove corrupted state and plugin data
rm universe/memories.json
rm -rf universe/SimpleClaims/
rm -rf universe/BarterShop/
rm -rf universe/SimpleStorage/
rm -rf universe/mods/
rm -rf universe/players/
rm -f universe/warps.json
rm -rf universe/worlds/default

# Restart server - Hytale will regenerate everything
```

---

### 2. "Failed to load any asset packs" / Missing Assets.zip

**Symptoms:**
```
WARN [AssetModule|P] Failed to load manifest for pack at Assets.zip
INFO [HytaleServer] Shutting down... 'Failed to load any asset packs'
```

**Cause:** Missing or corrupted `Assets.zip` file (often deleted during cleanup).

**Solution A - Re-download using hytale-downloader:**
```bash
cd /var/lib/pterodactyl/volumes/<hytale-uuid>

# Download full server package
./hytale-downloader-linux-amd64 -download-path Server-Package.zip

# Extract the nested Assets.zip
unzip -j Server-Package.zip Assets.zip

# Verify file size (should be ~3.3GB)
ls -lh Assets.zip

# Clean up
rm Server-Package.zip

# Restart server
```

**Solution B - Upload from local files:**
- Upload your local Hytale `Assets.zip` (3.3GB) via SFTP/Pterodactyl file manager
- Place in server root directory

---

### 3. Invalid/Corrupted Assets.zip

**Symptoms:**
```
WARN [AssetModule|P] Skipping pack at Assets.zip: missing or invalid manifest.json
```

**Cause:** The downloaded file is the server package (1.4GB), not the actual Assets.zip (3.3GB).

**Solution:**
```bash
# The hytale-downloader gives you a package containing Assets.zip
# You need to extract the real Assets.zip from inside it

# Rename the downloaded package
mv Assets.zip Server-Package.zip

# Extract the actual Assets.zip
unzip -j Server-Package.zip Assets.zip

# Verify size - should be ~3.3GB, not 1.4GB
ls -lh Assets.zip
```

---

## File Structure Reference

### Critical Files (DO NOT DELETE)
```
/var/lib/pterodactyl/volumes/<uuid>/
├── Assets.zip              # 3.3GB - Core game assets (CRITICAL)
├── Server/                 # Server binaries
├── hytale-downloader       # Downloader tool
├── config.json             # Server configuration
└── universe/               # World data
    ├── memories.json       # World state tracking
    ├── worlds/             # World folders
    │   └── default/        # Default world
    ├── SimpleClaims/       # Plugin: Claims system
    ├── BarterShop/         # Plugin: Economy
    ├── SimpleStorage/      # Plugin: Storage
    ├── mods/               # Plugin: Mod data
    └── players/            # Player data
```

### Safe to Delete (for cleanup)
```
/backups/                   # Old world backups
*.log                       # Old log files
universe-backup-*.tar.gz    # Manual backups you created
Server-Package.zip          # After extracting Assets.zip
```

### NEVER Delete These
```
Assets.zip                  # Core game assets
Server/                     # Server binaries
hytale-downloader*          # Needed for updates
config.json                 # Server settings
.hytale-downloader-credentials.json  # Auth tokens
```

---

## NC1 Cleanup Best Practices

### ❌ DANGEROUS Commands
```bash
# DO NOT USE THESE - They delete critical files:
rm -f /var/lib/pterodactyl/volumes/<uuid>/*.zip
rm -rf /var/lib/pterodactyl/volumes/<uuid>/backups
```

### ✅ SAFE Cleanup Commands
```bash
# Instead, be specific:
rm -f /var/lib/pterodactyl/volumes/<uuid>/backup*.zip
rm -f /var/lib/pterodactyl/volumes/<uuid>/Server-Package.zip
rm -rf /var/lib/pterodactyl/volumes/<uuid>/backups/

# Always verify before deleting:
ls -lah /var/lib/pterodactyl/volumes/<uuid>/*.zip
```

---

## Quick Reference: Hytale Downloader

```bash
# Check available version
./hytale-downloader-linux-amd64 -print-version

# Download latest release
./hytale-downloader-linux-amd64 -download-path Assets.zip

# Download to specific path
./hytale-downloader-linux-amd64 -download-path /path/to/save.zip

# Use different patchline (beta/experimental)
./hytale-downloader-linux-amd64 -patchline beta -download-path Assets.zip

# Check for downloader updates
./hytale-downloader-linux-amd64 -check-update
```

---

## Recovery Checklist

If Hytale won't start, follow this checklist:

1. **Check Assets.zip exists and is 3.3GB:**
   ```bash
   ls -lh Assets.zip
   ```

2. **Check for error in latest log:**
   ```bash
   tail -100 logs/latest.log
   ```

3. **Verify config.json is valid:**
   ```bash
   cat config.json
   ```

4. **Check universe/worlds/default exists:**
   ```bash
   ls -la universe/worlds/
   ```

5. **If world corruption suspected:**
   - Back up universe folder
   - Delete memories.json and plugin databases
   - Delete universe/worlds/default
   - Restart server

6. **If Assets.zip missing:**
   - Use hytale-downloader to re-download
   - Extract nested Assets.zip from package
   - Verify 3.3GB file size

---

## When to Wipe vs. Repair

### Repair (Keep World Data):
- World won't load: Delete memories.json
- Plugin errors: Delete plugin databases
- Player issues: Delete specific player file

### Wipe (Fresh Start):
- Unrecoverable corruption
- Want clean vanilla server
- Testing new configurations

```bash
# Full wipe (DESTRUCTIVE):
rm -rf universe/
# Server will regenerate fresh world on next start
```

---

## Support & Resources

- Hytale Server Documentation: Check official docs
- Firefrost Gaming Gitea: `git.firefrostgaming.com`
- This guide stored in: `docs/troubleshooting/hytale-troubleshooting-guide.md`

---

**Last Updated:** 2026-02-16  
**Tested On:** Hytale Server Version 2026.02.06-aa1b071c2