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)
The game will now automatically switch to offline mode if authentication fails (as of January 2026 hotfix)

Thread & Component Errors

”Assert not in thread!” Error

Problem: When accessing entity components, you get:


java.lang.IllegalStateException: Assert not in thread!
Thread[#108,WorldThread - default,5,InnocuousForkJoinWorkerThreadGroup]
but was in Thread[#75,Scheduler,5,main]

Cause: You’re trying to access ECS components from the wrong thread. Component operations must run on the world thread.

Solutions:

For Commands: Use AbstractPlayerCommand instead of CommandBase


// WRONG - CommandBase runs on scheduler thread
public class MyCommand extends CommandBase {
    protected void executeSync(CommandContext context) {
        // This crashes!
        store.getComponent(ref, CustomComponent.getComponentType());
    }
}
 
// CORRECT - AbstractPlayerCommand provides thread-safe context
public class MyCommand extends AbstractPlayerCommand {
    protected void execute(Ref<EntityStore> ref, Store<EntityStore> store, CommandContext ctx) {
        // Safe - runs on world thread
        store.getComponent(ref, CustomComponent.getComponentType());
    }
}

For Async Events: Use world.execute() to schedule on world thread


world.execute(() -> {
    // Safe to access components here
    CustomComponent component = store.getComponent(ref, CustomComponent.getComponentType());
});

For Event Systems: Use EntityEventSystem which handles threading automatically

See Thread Safety Guide for detailed patterns.

Component Returns Null Unexpectedly

Problem: store.getComponent() returns null even though the entity should have the component.

Solutions:

Verify you’re using the correct ComponentType (e.g., Player.getComponentType())
Check if you’re on the correct thread (see above)
Ensure the entity still exists and hasn’t been destroyed
For custom components, verify registration in setup()

Plugin Issues

Legal & EULA (Modding)

Status: Official policy has not been published yet.

Community Questions:

Copyrighted content in mods (e.g., fan IP)
Paid or paywalled mods
Redistribution and asset licensing

Until official guidance exists, assume standard copyright rules apply and avoid distributing unlicensed third-party content.

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.

ZipException on Plugin Reload

Problem: After executing /plugin reload <pluginId>, you get:


java.util.zip.ZipException: ZipFile invalid LOC header (bad signature)

Cause: The plugin JAR file was modified while the server was running, corrupting the file handle.

Solution: Hot-reload is currently broken for most cases. Always:

Stop the server completely
Replace the plugin JAR
Start the server fresh

There is no working hot-reload for plugins at this time. Use external tools like HotSwap for code changes during development.

”Cannot resolve symbol ‘hypixel’” Error

Problem: IDE shows Cannot resolve symbol 'hypixel' or similar import errors.

Causes & Solutions:

Missing HytaleServer.jar dependency


// build.gradle.kts
dependencies {
    compileOnly(files("libs/HytaleServer.jar"))
}

Java Version Mismatch
- Ensure you’re using Java 25 (not 21 or earlier)
- Check IDE project SDK settings
- Verify sourceCompatibility and targetCompatibility in build.gradle
IDE Cache Issues
- IntelliJ: File > Invalidate Caches > Invalidate and Restart
- Reimport Gradle project

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

OAuth2 Device Flow Errors

Problem: When running /auth login device, you get:


Device authorization request failed

Cause: The device flow may be blocked or have connectivity issues.

Solutions:

Use browser authentication instead:
```
/auth login browser
```
After successful login, persist credentials:
```
/auth persistence encrypted
```
Check for clock sync issues: Ensure your server’s system clock is accurate. Outdated time can cause token validation failures.

”Cannot save credentials” Warning

Problem: Server logs show:


[EncryptedAuthCredentialStore] Cannot save credentials - no encryption key available

Solutions:

Run /auth persistence encrypted to set up encrypted storage
Ensure the server has write permissions to its config directory
For development, you can use /auth insecure (not recommended for production)

Player Token/Authentication Issues

Problem: Players get kicked or can’t join due to token issues, including “invalid token” errors.

Solutions:

Clock Sync Issue: Player’s PC clock may be wrong
- Have player check and update their system time
- The launcher now warns players if their computer time is out of date
- This has been a common cause of authentication failures and was addressed in the January 2026 hotfixes
Token Refresh: Try having the player:
- Close the game completely
- Restart the Hytale launcher
- Rejoin the server

DNS Issues: Try flushing DNS


# Windows
ipconfig /flushdns
 
# macOS
sudo dscacheutil -flushcache
 
# Linux
sudo systemd-resolve --flush-caches

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