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:

# 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:

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:

# 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

# 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

# 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

# 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:

   ls -lh Assets.zip
   

2. Check for error in latest log:

   tail -100 logs/latest.log
   

3. Verify config.json is valid:

   cat config.json
   

4. Check universe/worlds/default exists:

   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

# 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