Aikar Flags for Paper JVM tuning to reduce lag spikes
If you run a Paper Minecraft server and you get random TPS dips, the villain is often Java garbage collection (GC) plus messy memory allocation. Aikar Flags are a well-known set of JVM startup flags that Paper documents as a recommended baseline to keep performance more consistent and reduce nasty GC spikes.
What are Aikar Flags
Aikar Flags are JVM startup parameters tuned for Minecraft-style workloads (lots of short-lived objects, frequent allocations) and centered around G1GC. Paper’s docs describe them as a set designed to improve Paper server performance, and they provide a ready-to-use recommended startup command.
Official links
Paper docs — Aikar’s flags: https://docs.papermc.io/paper/aikars-flags/
Paper docs — System properties warning: https://docs.papermc.io/paper/reference/system-properties/
Aikar’s original JVM tuning post: https://aikar.co/2018/07/02/tuning-the-jvm-g1gc-garbage-collector-flags-for-minecraft/
flags.sh generator: https://flags.sh/
Recommended JVM startup flags for Paper
Paper publishes this baseline command (you only change Xms/Xmx and your jar name).
Before you copy-paste: this is meant for Paper. If you’re not sure what a flag does, don’t freestyle random JVM flags—Paper explicitly warns that JVM flags can alter how things behave.
java -Xms10G -Xmx10G \
-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch \
-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 \
-Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true \
-jar paper.jar --noguiWhat to understand (so it’s not just “magic words”):
-Xms/-Xmxset the heap size. Paper’s guidance is to keep them equal for consistency.The rest mainly tunes G1GC to avoid huge pause spikes and keep behavior steadier under load.
How much RAM should you allocate
This is where people speedrun their own outage.
Paper’s guidance:
Do not allocate all available memory on a shared host.
Reduce
Xms/Xmxby roughly 1000–1500MB below what your host claims you have, to avoid OOM or the OOM killer, and to leave room for the OS.Paper recommends 6–10GB minimum even for low player counts, because G1GC generally operates better with more memory—up to a point (after that, diminishing returns).
Example: host says “8GB”? Paper’s doc literally suggests ~6500MB for safety.
Generate a clean start script (instead of hand-editing)
Paper says this page is explanatory, and points you to a script generator for building a proper start script.
If you want a dead-simple generator UI, flags.sh generates Minecraft server start scripts too.
Enable GC logging to diagnose “lag spikes” for real
If you suspect GC pauses, turn on GC logging and check what’s happening during spikes.
Paper includes a Java 11+ GC logging option on the same page.
-Xlog:gc*:logs/gc.log:time,uptime:filecount=5,filesize=1MWhat this gives you:
A rolling log of GC activity you can correlate with TPS drops and player spikes (instead of guessing).
Common mistakes with Aikar Flags
Setting Xmx to “all my RAM” → OS starves, OOMKiller shows up, server dies.
Thinking more RAM always = more performance → Paper explicitly calls out diminishing returns.
Mixing random JVM flags from old Reddit posts → Paper warns flags can change behavior; use a known baseline first.
Conclusion
Aikar Flags are still a solid baseline for Paper: start with the recommended command, size memory safely (leave headroom), and enable GC logs if you’re chasing spikes. That combo fixes a surprising amount of “mystery lag” without touching gameplay settings.
