Common Issues & Solutions

Troubleshooting guide based on real problems and solutions from the Hytale developer community.

Connection Issues

”Server requires development mode”

Problem: Players see “Server requires development mode” when trying to connect.

Solutions:

Check Authentication Settings
- Server may have auth disabled with /auth insecure
- Verify your game has development mode enabled in settings
- Friends connecting may need to enable dev mode too

Verify Server Configuration


# Check if server has authentication disabled
# Look for auth settings in server config

Development Mode Location
- In game settings
- Under developer/advanced options
- Enable “Allow development servers"

"Failed to connect / Connection timeout”

Problem: Cannot connect to server, connection times out.

Solutions:

Port Forwarding
- Ensure port 5520 is forwarded correctly
- See Port Forwarding Guide
- Test with port checker tool

Firewall Rules


# Windows
netsh advfirewall firewall add rule name="Hytale" dir=in action=allow protocol=TCP localport=5520
 
# Linux (UFW)
sudo ufw allow 5520/tcp
 
# Check firewall status
sudo ufw status

Verify Server is Running
- Check server console for errors
- Ensure server finished starting up
- Look for “Server started” or similar message
CGNAT Issues

“If you’re behind CGNAT (carrier-grade NAT), port forwarding won’t work - you’ll need a VPS or tunneling service like Playit.gg” - From Discord
Test Local Connection First
- Try connecting via localhost:5520
- If local works but external doesn’t, it’s a network issue
- If local doesn’t work, it’s a server issue

”Server authentication unavailable”

Problem: Authentication services not responding.

Solutions:

Wait for Hytale authentication services to come back online
Check Hytale status page or Discord for service updates
Use /auth insecure for LAN testing only (not recommended for public servers)

Plugin Issues

Plugin Not Loading

Problem: Plugin doesn’t appear in /plugins list or shows “missing or invalid manifest.json”.

Solutions:

Verify manifest.json exists and is valid

The manifest.json must be in the JAR root (inside src/main/resources/):
```
{
  "Group": "com.example",
  "Name": "MyPlugin",
  "Version": "1.0.0",
  "Main": "com.example.myplugin.MyPlugin",
  "ServerVersion": "*"
}
```
“Skipping pack at MyPlugin: missing or invalid manifest.json” - This error means the manifest is missing or has invalid JSON syntax.

Check Plugin Structure


my-plugin.jar
├── manifest.json          # Must be at JAR root!
├── com/
│   └── example/
│       └── myplugin/
│           └── MyPlugin.class
└── ...

Enable Development Mode
- Check game settings
- Ensure dev mode is enabled
- Required for custom plugins
Check Server Logs
- Look for plugin loading errors
- Check for class loading exceptions
- Verify Java version compatibility
Plugin Location
- Place in /mods folder
- NOT in root directory or other locations

”Missing or invalid manifest.json” Error

Problem: Server logs show Skipping pack at MyPlugin: missing or invalid manifest.json

Solutions:

Verify manifest.json location
- Must be at the root of your JAR file
- In Gradle/Maven projects: src/main/resources/manifest.json
Validate JSON syntax
- Use a JSON validator
- Check for missing commas, quotes, or brackets
- Field names are case-sensitive (Group not group)

Required fields


{
  "Group": "your.group.name",
  "Name": "PluginName",
  "Version": "1.0.0",
  "Main": "your.group.name.MainClass"
}

Example working manifest


{
  "Group": "UltimateTeam",
  "Name": "UltimateLobby",
  "Version": "1.0.0",
  "Authors": [{ "Name": "Developer" }],
  "Main": "com.example.ultimateLobby.Main",
  "ServerVersion": "*"
}

”Class not found” Errors

Problem: Plugin fails to load with ClassNotFoundException.

Solutions:

Shade Dependencies


// Gradle: Use shadow plugin
plugins {
    id("com.github.johnrengelman.shadow") version "8.1.1"
}
 
tasks.shadowJar {
    // Relocate dependencies to avoid conflicts
    relocate("org.example", "com.myplugin.shaded.example")
}

For Kotlin
- Shade Kotlin standard library into JAR
- Community recommendation for Kotlin plugins
Check Dependencies
- Ensure all required libraries are included
- Use compileOnly for server JAR
- Use implementation for external libraries

Plugin Reload Issues

Problem: /plugin reload doesn’t work or causes file locking issues.

Solutions:

From Discord:

“Most developers restart server for testing” - Community consensus

Recommended Workflow:

Build plugin JAR
Stop server
Replace JAR in /mods folder
Start server

Alternative: Use development server that auto-restarts on changes.

Performance Issues

High RAM Usage

Problem: Server consuming excessive memory.

Solutions:

Garbage Collection Tuning


# G1GC (recommended)
java -Xms2G -Xmx8G -XX:+UseG1GC -XX:MaxGCPauseMillis=200 -jar server.jar
 
# ZGC (trades CPU for lower pause times)
java -Xms2G -Xmx8G -XX:+UseZGC -jar server.jar

Pre-generate Worlds

“Pre-generate your worlds before opening to players - exploration is the biggest RAM consumer.” - From Discord
Reduce View Distance
- Lower in server config
- Reduces chunk loading
Chunk Management
- Use chunk unloading plugins
- Limit loaded chunks
- Pre-generate spawn area
Player Distribution

“4 players flying in different directions crashed 8GB server” - Community testing

RAM usage increases dramatically when players spread out exploring.

Server Lag / TPS Drop

Problem: Server tick rate dropping below 30 TPS.

Solutions:

Identify Bottleneck
- Use performance profiler
- Check which world/plugin is causing lag
- Monitor CPU and disk I/O
Disable Unused Modules
- Server has 70+ modules that can be disabled
- Turn off features you don’t need
- See server configuration documentation
Optimize Plugins
- Remove or replace laggy plugins
- Profile plugin event handlers
- Use asynchronous operations
Hardware Upgrade
- More RAM if memory-constrained
- Better CPU for computation
- SSD/NVMe for disk I/O

Authentication & Security

Authentication Errors

Problem: Various authentication-related issues.

Solutions:

Development vs Production
- Development: /auth insecure (testing only)
- Production: Use proper authentication
Friend Connection Issues
- Ensure both parties have compatible auth settings
- Check if friend has dev mode enabled
- Verify server whitelist settings

DDoS Attacks

Problem: Server under DDoS attack.

Recommended Protection (from Discord):

TCPShield: Popular in Minecraft, may work
GSL: Confirmed working solution
GCore: Alternative protection
Datapacket: Another option

CloudFlare Note: Standard proxy doesn’t support game ports - need Spectrum (paid) or other solutions.

Building & Development

Build Failures

Problem: Plugin won’t compile or build.

Solutions:

Java Version Mismatch


# Check Java version
java -version
javac -version
 
# Ensure using Java 17+

Gradle Issues


# Clear Gradle cache
./gradlew clean
 
# Rebuild
./gradlew build --refresh-dependencies

Maven Issues


# Clean and rebuild
mvn clean install
 
# Update dependencies
mvn dependency:purge-local-repository

IDE Not Recognizing Classes

Problem: IDE shows errors but code compiles.

Solutions:

IntelliJ IDEA
- File > Invalidate Caches > Invalidate and Restart
- Reimport Gradle/Maven project
- Check Project Structure > SDKs
VS Code
- Reload Java projects
- Check Java extension settings
- Verify language server is running

Networking Issues

SRV Records Not Working

Problem: SRV records don’t resolve.

Solution:

“SRV records NOT supported initially (A records only)” - From Discord

Use A records or direct IP:Port connections.

Transfer Packet Issues

Problem: Issues with server transfer functionality.

Solutions:

Verify Signature
- Always verify transfer packet signatures
- Prevents unauthorized transfers
Payload Size
- Max 4KB payload
- Compress data if needed
Backend Setup
- Still need proxies for load balancing
- Transfer packets don’t replace proxies entirely

Database & Data

Data Not Persisting

Problem: Player data or configuration not saving.

Solutions:

File Permissions


# Check permissions
ls -la /path/to/server/
 
# Fix permissions
chown -R hytale:hytale /path/to/server/
chmod -R 755 /path/to/server/

Serialization Issues
- Verify JSON/YAML syntax
- Check for serialization errors in logs
- Test save/load cycle
Database Connection
- Verify credentials
- Check connection string
- Ensure database server is running

Configuration Errors

Problem: Config file not loading or causing errors.

Solutions:

JSON Validation
- Use JSON validator tool
- Check for syntax errors
- Verify proper escaping
Config Location
- Verify config file is in correct location
- Check if server is reading from right path
- Look for typos in filename

Platform-Specific Issues

macOS Support

Status: Delayed due to Apple code signing requirements.

Workaround:

Use Windows or Linux for now
Wait for official macOS release
Community may provide unsigned builds (use at own risk)

Linux Issues

Flatpak Support: Confirmed available


# Install via Flatpak
flatpak install hytale-server

FreeBSD

Status: Community discussion, no official support yet.

Troubleshooting Checklist

When encountering issues, check:

Getting Help

Before Asking

Check server logs
Search this documentation
Search Discord history
Try basic troubleshooting steps

Where to Ask

Discord: Active community for real-time help
GitHub Issues: For plugin-specific problems
Forums: For detailed discussions

What to Include

Server version
Plugin version (if applicable)
Full error message from logs
Steps to reproduce
What you’ve already tried

Community Tips

“Always check logs first - 90% of issues are explained there” - Discord advice

“Port forwarding issues? Test with a different port first to verify your router config” - Troubleshooting tip

“Start with minimal plugins, then add one at a time to identify conflicts” - Plugin debugging

Next Steps

Server Setup - Proper server configuration
Performance - Optimization guides
Plugin Development - Development best practices