Hytale Server Log Files Guide
Master the art of reading and analyzing Hytale server logs. Learn to diagnose issues, track performance, and debug problems efficiently using your server's log files.
Quick Navigation
Log File Locations
Hytale server logs are stored in the logs/ directory within your server installation folder.
Directory Structure
hytale-server/ ├── logs/ │ ├── latest.log # Current session log │ ├── 2025-01-15-1.log.gz # Previous sessions (compressed) │ ├── 2025-01-15-2.log.gz │ ├── 2025-01-14-1.log.gz │ └── debug/ │ ├── debug-2025-01-15.log # Debug level logs │ └── trace-2025-01-15.log # Trace level logs ├── crash-reports/ │ ├── crash-2025-01-15-093045.txt │ └── crash-2025-01-14-183010.txt └── server.log.properties # Logging configuration
Key Log Files
latest.log
Purpose: Real-time log of current server session
Contains: Server startup, player events, errors, warnings
When to check: Active troubleshooting, monitoring current issues
YYYY-MM-DD-N.log.gz
Purpose: Archived logs from previous sessions
Contains: Historical server activity (compressed with gzip)
When to check: Investigating past issues, auditing history
crash-reports/*.txt
Purpose: Detailed crash dumps when server terminates unexpectedly
Contains: Stack traces, thread dumps, system info
When to check: After any server crash for root cause analysis
debug/*.log
Purpose: Verbose logging for development and deep troubleshooting
Contains: Detailed packet traces, state changes, plugin internals
When to check: Complex issues requiring detailed trace information
Accessing Log Files
# View latest log in real-time (Linux/macOS) tail -f logs/latest.log # Windows equivalent (PowerShell) Get-Content logs/latest.log -Wait -Tail 50 # Extract and view compressed log gunzip -c logs/2025-01-15-1.log.gz | less # Search for specific error grep "ERROR" logs/latest.log # Count errors by type grep "ERROR" logs/latest.log | sort | uniq -c | sort -rn
Understanding Log Levels
Hytale uses standard log levels to categorize messages by severity.
TRACE
Usage: Extremely detailed diagnostic information
Example: Individual packet processing, every state change
⚠️ Only enable for debugging specific issues - generates massive log files
DEBUG
Usage: Detailed information for diagnosing issues
Example: Plugin initialization, configuration loading, major events
INFO
Usage: General informational messages about server operation
Example: Server startup, player joins/leaves, world saves
✓ Default log level - good balance of detail without noise
WARN
Usage: Potentially harmful situations that don't stop execution
Example: Deprecated API usage, minor configuration issues, recoverable errors
⚠️ Review warnings periodically - they indicate technical debt
ERROR
Usage: Error events that might still allow continued operation
Example: Plugin failures, failed connections, caught exceptions
🔴 Requires immediate attention - indicates broken functionality
FATAL
Usage: Severe errors causing server termination
Example: Unrecoverable crashes, critical resource failures
💀 Server is shutting down - check crash reports for details
Configuring Log Level
Adjust logging verbosity in server.log.properties:
# server.log.properties # Root logger level (default: INFO) log.level=INFO # Plugin-specific logging log.level.com.example.myplugin=DEBUG # Network debugging log.level.com.hytale.network=TRACE # Reduce spam from specific packages log.level.com.hytale.worldgen=WARN
Reading Log Entries
Understanding the structure of log entries helps you quickly identify relevant information.
Log Entry Format
[10:45:32] [Server thread/INFO] [com.hytale.server.Network]: Player Steve connected from /192.168.1.100:54321 │ │ │ │ │ │ │ │ │ └─ Message │ │ │ └─ Logger name (class/component) │ │ └─ Log level │ └─ Thread name └─ Timestamp (HH:MM:SS)
Each component provides context for understanding what happened, where, and why.
Common Thread Names
Server thread
Main game loop, tick processing, player events
Network thread
Connection handling, packet processing, authentication
Worker-N
Async tasks, chunk generation, I/O operations
Plugin-PluginName
Plugin-specific threads for background tasks
Stack Traces
When errors occur, stack traces show the chain of method calls leading to the error:
[ERROR] Exception in plugin MyPlugin
java.lang.NullPointerException: Cannot invoke "Player.getName()" because "player" is null
at com.example.myplugin.EventHandler.onPlayerJoin(EventHandler.java:45)
at com.hytale.events.EventBus.dispatch(EventBus.java:128)
at com.hytale.server.PlayerManager.handleJoin(PlayerManager.java:201)
at com.hytale.network.PacketHandler.processLogin(PacketHandler.java:87)
at com.hytale.network.NetworkManager.channelRead(NetworkManager.java:156)Reading stack traces:
- Top line: Actual error message
- First entry: Where error occurred (EventHandler.java:45)
- Following entries: Call chain from bottom (entry point) to top (error location)
- Your code: Lines with your package name (com.example.myplugin)
Filtering Logs
Extract relevant information from large log files:
# Find all errors grep "ERROR" logs/latest.log # Find errors from specific plugin grep "ERROR.*MyPlugin" logs/latest.log # Find player join events grep "Player.*joined" logs/latest.log # Get last 100 lines tail -n 100 logs/latest.log # Find errors with context (3 lines before/after) grep -C 3 "ERROR" logs/latest.log # Count errors by hour grep "ERROR" logs/latest.log | cut -d'[' -f2 | cut -d':' -f1 | sort | uniq -c
Common Errors & Solutions
Out of Memory (OOM)
Cause: Server ran out of allocated RAM
Solutions:
- Increase RAM allocation:
java -Xmx8G - Reduce view distance in server properties
- Check for memory leaks in plugins
- Optimize world generator settings
- Clear old chunks periodically
Port Already in Use
Cause: Another process is using port 5520
Solutions:
- Stop the existing server instance
- Find and kill the process:
netstat -ano | findstr 5520 - Change server port in configuration (if supported)
- Reboot server if process is stuck
Plugin Dependency Missing
Cause: Plugin requires another plugin that isn't installed
Solutions:
- Install the required dependency plugin
- Check plugin documentation for requirements
- Verify plugin compatibility with server version
- Update all plugins to compatible versions
World Corruption
Cause: World data file corruption (server crash, disk error)
Solutions:
- Restore from backup if available
- Delete corrupted region file (world/region/r.0.0.mca) - chunk will regenerate
- Run world repair tool if available
- Set up automatic backups to prevent data loss
Authentication Failure
Cause: OAuth2 authentication issue with Hytale services
Solutions:
- Check server authentication configuration (see Authentication Guide)
- Verify server has internet connectivity
- Check if Hytale auth servers are operational
- Refresh OAuth2 credentials if expired
- Player should try restarting their client
Tick Loop Warning
Cause: Server cannot process game ticks fast enough
Solutions:
- Upgrade server hardware (CPU, RAM)
- Reduce player count or view distance
- Optimize plugins (check for infinite loops, heavy operations)
- Profile server to find bottlenecks
- Install performance optimization plugins
Performance Analysis from Logs
Extract performance insights from server logs to identify bottlenecks.
Tick Time Monitoring
Hytale servers run at 20 ticks per second (50ms per tick). Look for warnings about slow ticks:
Analysis:
- Occasional slow ticks (1-2 per minute): Normal, no action
- Frequent slow ticks (10+ per minute): Performance issue
- Consistently slow (>100ms): Server severely overloaded
Chunk Generation Lag
[INFO] Generated 1000 chunks in 45s (22.2 chunks/s) [WARN] Chunk generation queue: 5000 pending
High pending chunk counts cause lag when players explore new areas.
Optimization:
- Pre-generate world before opening server
- Reduce view distance to minimize chunk loading
- Allocate more CPU cores to chunk generation threads
Memory Usage Patterns
[INFO] Memory: 3200MB used / 8192MB allocated (39%) [INFO] Garbage collection: Young gen (15ms), Old gen (0ms)
Healthy pattern: Memory usage oscillates between 40-70%
Warning signs:
- Memory usage steadily increasing: Possible memory leak
- Frequent Old Gen GC: Heap size too small
- GC pauses >100ms: Heap too large or fragmented
Network Performance
[INFO] Network stats: 45 MB/s in, 120 MB/s out [INFO] Packets: 15,000/s in, 30,000/s out [WARN] Player Steve timing out (30s no response)
Monitor network stats to identify bandwidth issues or connection problems.
Plugin Performance
[WARN] Plugin 'BadPlugin' event handler took 150ms [DEBUG] Event timings: - BadPlugin.onPlayerMove: 145ms (slow!) - GoodPlugin.onPlayerMove: 0.2ms - WebServer.onPlayerJoin: 1.5ms
Identify plugins causing performance issues and consider removing or replacing them.
Plugin Debugging
Debug issues with Hytale server plugins using log analysis.
Enable Debug Logging
Enable verbose logging for specific plugins in server.log.properties:
# Enable debug for your plugin log.level.com.example.myplugin=DEBUG # Enable trace for detailed packet info log.level.com.example.myplugin.network=TRACE
Common Plugin Issues
Plugin Won't Load
Check: Plugin JAR in correct location, no missing dependencies, compatible with server version
Event Handler Exception
Check: Null safety in event handlers, validate player/entity existence before use
Deprecated API Usage
Check: Plugin documentation for API changes, update plugin to use modern APIs
Adding Debug Logging to Your Plugin
Add logging to your custom plugins:
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class MyPlugin {
private static final Logger logger =
LoggerFactory.getLogger(MyPlugin.class);
public void onEnable() {
logger.info("MyPlugin enabled");
logger.debug("Config loaded: {}", config);
}
public void handleEvent(PlayerEvent event) {
logger.trace("Processing event: {}", event);
try {
// Your logic here
logger.debug("Event processed successfully");
} catch (Exception e) {
logger.error("Failed to process event", e);
}
}
}Log Management & Rotation
Manage log files to prevent disk space issues and maintain performance.
Automatic Log Rotation
Hytale automatically rotates logs daily and compresses old logs. Configure retention in server.log.properties:
# Log rotation settings log.rotation.max-size=100MB # Rotate when log exceeds size log.rotation.max-age=7 # Keep logs for 7 days log.rotation.compress=true # Compress old logs with gzip log.rotation.max-files=30 # Keep max 30 archived logs
Manual Log Cleanup
Clean up old logs manually if needed:
# Delete logs older than 30 days (Linux/macOS)
find logs/ -name "*.log.gz" -mtime +30 -delete
# Windows PowerShell
Get-ChildItem logs/*.log.gz | Where-Object {$_.LastWriteTime -lt (Get-Date).AddDays(-30)} | Remove-Item
# Keep only last 10 compressed logs
ls -t logs/*.log.gz | tail -n +11 | xargs rmCentralized Logging
For multi-server networks, send logs to central logging system:
ELK Stack (Elasticsearch, Logstash, Kibana)
Popular open-source solution for log aggregation, search, and visualization
Grafana Loki
Lightweight alternative to ELK, integrates well with Prometheus
Papertrail / Loggly
Cloud-based logging services with easy setup
Disk Space Monitoring
Set up alerts for low disk space to prevent log-related outages:
# Check disk usage (Linux)
df -h /path/to/server
# Monitor logs directory size
du -sh logs/
# Alert if logs exceed 10GB (example script)
LOG_SIZE=$(du -sm logs/ | cut -f1)
if [ $LOG_SIZE -gt 10000 ]; then
echo "Warning: Logs exceed 10GB!"
# Send alert email/notification
fiLog Analysis Tools
Tools to make log analysis easier and more efficient.
Command Line Tools
grep / ripgrep (rg)
Search for patterns in logs. ripgrep is much faster for large files.
less / tail
View and navigate log files. tail -f for real-time monitoring.
awk / sed
Process and transform log data for analysis.
GUI Log Viewers
Notepad++ (Windows)
Text editor with syntax highlighting for logs. Search, filter, and bookmark features.
Visual Studio Code
Extensions like "Log File Highlighter" add color coding and filtering.
BareTail (Windows)
Real-time log viewing with highlighting and filtering.
Console (macOS)
Built-in macOS tool for viewing system and application logs.
Web-Based Tools
Grafana + Loki
Query and visualize logs with powerful filtering. See our Prometheus guide for setup.
Kibana (ELK)
Elasticsearch-backed log search and visualization with dashboards and alerts.
Frequently Asked Questions
How do I enable debug logging without restarting the server?
Some servers support runtime log level changes via console commands like /log level DEBUG. Otherwise, modify server.log.properties and restart the server.
Can I send logs to a remote server automatically?
Yes, configure log forwarding using tools like Filebeat, Fluentd, or syslog. Point them to your logs/ directory and configure destination (ELK, Loki, Papertrail, etc.).
Why are my logs full of "[DEBUG]" messages I don't need?
Change the log level to INFO in server.log.properties:
This reduces noise while still showing important events and errors.
How long should I keep old logs?
Depends on your needs. 7-14 days is typical for active troubleshooting. If you have disk space and want audit trails, keep 30-90 days. For compliance, may need 1+ years.
Can I filter out specific log messages I don't care about?
Yes, configure log filters in server.log.properties:
# Reduce spam from specific loggers log.level.com.hytale.network.keepalive=WARN log.filter.contains=KeepAlivePacket
What should I do with crash reports?
Read the crash report to identify the cause (look for the exception and stack trace). If it's a plugin issue, report to plugin author with the crash report. If it's a Hytale bug, report to Hypixel Studios with crash report attached.
How can I monitor logs in real-time from a web browser?
Use a web-based server management panel (like Pterodactyl, Multicraft) which includes real-time log viewers. Alternatively, set up Grafana with Loki for professional log querying and visualization.
Related Guides
Need Help Debugging Your Server?
Our managed hosting includes 24/7 support with expert log analysis and troubleshooting. We handle the technical issues so you can focus on your community.
View Hosting Plans →