Fix OutOfMemoryError: Java Heap Space - Minecraft Server Memory Guide

# Fix OutOfMemoryError: Java Heap Space - Minecraft Server Memory Guide

OutOfMemoryError: Java heap space crashes occur when your Minecraft server runs out of allocated RAM. Fix it by increasing heap size with -Xmx flag (e.g., -Xmx8G for 8GB), matching -Xms to -Xmx for consistent allocation, and adding G1GC flags for efficient garbage collection. This guide shows proper memory configuration for stable server operation.

Understanding the Error

When Java logs "OutOfMemoryError: Java heap space", the JVM exhausted the maximum heap memory allocated via -Xmx. Minecraft servers hold the entire world, chunks, entities, and player data in RAM. Insufficient allocation causes crashes during chunk generation, player joins, or plugin operations.

Common Triggers:

• Worldgen loading hundreds of chunks simultaneously
• Memory leaks from poorly coded plugins
• Insufficient RAM for modpack requirements (1.20.1 modpacks need 8GB minimum)
• Garbage collection unable to free memory fast enough
• Too many entities loaded (mob farms, item drops)

Step-by-Step Fix

Step 1: Calculate Required RAM

Determine how much RAM your server needs:

Vanilla Minecraft (Paper/Spigot):

• 1-10 players: 4GB (-Xmx4G)
• 10-25 players: 8GB (-Xmx8G)
• 25-50 players: 12GB (-Xmx12G)

Modded Minecraft (Forge/Fabric):

• Small modpacks (<100 mods): 6-8GB
• Medium modpacks (100-200 mods): 8-12GB
• Large modpacks (200+ mods): 12-16GB

Memory Overhead: Allocate 1-2GB extra for OS and background processes. If your VPS has 8GB total RAM, allocate max 6GB to Minecraft.

Step 2: Set Heap Size with -Xms and -Xmx

Configure your server startup script with proper heap allocation:

# Basic startup command with heap size
java -Xms8G -Xmx8G -jar server.jar nogui

Flag Explanation:

• -Xms8G: Initial heap size (8 gigabytes)
• -Xmx8G: Maximum heap size (8 gigabytes)

Critical Rule: Always set -Xms equal to -Xmx. This prevents heap resizing during runtime, which causes lag spikes.

❌ WRONG: -Xms2G -Xmx8G (heap grows dynamically, causing stutter)

✅ CORRECT: -Xms8G -Xmx8G (heap size fixed, consistent performance)

Step 3: Add Garbage Collection Flags

G1GC (Garbage-First Garbage Collector) minimizes pause times and prevents memory fragmentation.

# Optimized startup with G1GC flags
java -Xms8G -Xmx8G \
  -XX:+UseG1GC \
  -XX:+ParallelRefProcEnabled \
  -XX:MaxGCPauseMillis=200 \
  -XX:+UnlockExperimentalVMOptions \
  -XX:+DisableExplicitGC \
  -XX:G1NewSizePercent=30 \
  -XX:G1MaxNewSizePercent=40 \
  -XX:G1HeapRegionSize=8M \
  -XX:G1ReservePercent=20 \
  -XX:G1HeapWastePercent=5 \
  -XX:G1MixedGCCountTarget=4 \
  -XX:InitiatingHeapOccupancyPercent=15 \
  -XX:G1MixedGCLiveThresholdPercent=90 \
  -XX:G1RSetUpdatingPauseTimePercent=5 \
  -XX:SurvivorRatio=32 \
  -XX:+PerfDisableSharedMem \
  -XX:MaxTenuringThreshold=1 \
  -jar server.jar nogui

Flag Breakdown:

• UseG1GC: Enable G1 garbage collector (better than default for Minecraft)
• MaxGCPauseMillis=200: Target 200ms max pause (prevents TPS drops)
• DisableExplicitGC: Ignore System.gc() calls from plugins
• G1NewSizePercent=30 / G1MaxNewSizePercent=40: Allocate 30-40% heap for young generation
• InitiatingHeapOccupancyPercent=15: Start GC when heap is 15% full (prevents buildup)

Step 4: Verify Memory Allocation

After starting the server, confirm heap size:

# In-game command (requires permission)
/spark heapsummary

# Expected output:
# Heap Usage: 3.2 GB / 8.0 GB (40%)
# Memory Pools:
#   G1 Eden Space: 1.8 GB
#   G1 Old Gen: 1.4 GB

If the max heap shows less than your -Xmx value, your JVM flags aren't being applied.

Step 5: Detect Memory Leaks

If crashes persist after increasing RAM, you have a memory leak.

Install Spark Profiler:

# Download Spark
wget https://ci.lucko.me/job/spark/lastSuccessfulBuild/artifact/spark-bukkit/build/libs/spark-bukkit.jar
mv spark-bukkit.jar plugins/

Run Heap Analysis:

# In-game command
/spark heapdump

# Wait 1-2 minutes for analysis
# Open the generated URL in browser

Common Leak Sources:

• Player data not being cleared after logout
• Chunk references retained after unload
• Event listeners not unregistered by plugins
• Large collections (HashMaps) growing unbounded

Example Leak Fix:

If Spark shows "PlayerData objects: 45,000 instances", you have a player data leak. Identify the plugin creating PlayerData and update/remove it.

Step 6: Optimize for Container Environments

If running in Docker/Kubernetes, use container-aware JVM flags:

# Container-aware heap allocation
java -XX:+UseContainerSupport \
  -XX:MaxRAMPercentage=75.0 \
  -XX:InitialRAMPercentage=75.0 \
  -jar server.jar nogui

Container Flags:

• UseContainerSupport: Detect container memory limits
• MaxRAMPercentage=75.0: Allocate 75% of container memory to heap
• Avoids hardcoding -Xmx values that conflict with container limits

Step 7: Emergency Fix for Immediate Crash

If server crashes during startup before you can edit startup script:

# Quick fix: allocate all available RAM
java -Xms$(free -g | awk '/^Mem:/{print int($2*0.8)}')G \
     -Xmx$(free -g | awk '/^Mem:/{print int($2*0.8)}')G \
     -jar server.jar nogui

This automatically allocates 80% of available system RAM. Not recommended for production (use fixed values), but useful for emergency recovery.

The MANAfuel Difference

The manual configuration above works, but requires understanding JVM internals, calculating heap sizes, and debugging memory leaks with profiling tools. On MANAfuel, Bob handles memory allocation dynamically.

You: "Bob, my server keeps crashing with OutOfMemoryError."

Bob: "Analyzing heap dump. Your server is running a 180-mod modpack with only 6GB allocated. Modpack manifest recommends 10GB minimum. I've scaled your deployment to 12GB RAM and configured G1GC for your workload. I also detected a memory leak in 'CustomNPCs' plugin version 1.2.3—I've updated to 1.2.5 which fixes the PlayerData retention bug. Server is stable."

The Grid's infrastructure dynamically allocates memory based on actual usage. Bob monitors heap usage and scales resources before crashes occur. No startup script editing. No JVM flag tuning.

Claim Your Founder Spot →

Frequently Asked Questions

# ZGC flags (Java 17+, 16GB+ RAM)
java -Xms16G -Xmx16G \
  -XX:+UseZGC \
  -XX:+ZGenerational \
  -jar server.jar nogui

free -h
# Allocate max 80% of "available" memory to Minecraft