Which JVM flags actually matter for a modded Minecraft server

The two that matter most

Before any flag list: the right Java version and a sane heap size account for more than every tuning flag combined.

• Minecraft 1.17–1.20.4 wants Java 17; 1.20.5+ wants Java 21; 1.16 and earlier want Java 8. Getting this wrong produces UnsupportedClassVersionError.
• -Xmx around 75% of physical RAM, and -Xms equal to it. See how much RAM.

What Aikar's flags are

A widely-copied G1GC tuning set aimed at one goal: avoid long garbage collection pauses, even at the cost of slightly more total GC work. A GC pause is a frozen server, so trading throughput for shorter pauses is the right trade for a game.

The ones doing the real work:

• -XX:+UseG1GC — the collector the rest assumes. Default on modern Java, so usually redundant now.
• -XX:MaxGCPauseMillis=200 — the target pause. This is the flag that most directly reflects the goal.
• -XX:G1NewSizePercent / G1MaxNewSizePercent — a larger young generation, because Minecraft allocates enormous numbers of short-lived objects per tick.
• -XX:+ParallelRefProcEnabled — reference processing in parallel rather than during the pause.
• -XX:+PerfDisableSharedMem — stops a stall when the JVM writes perf data to a filesystem that happens to be slow.

What to be careful with

• Do not copy a flag list for a different heap size. Several of these are percentages tuned against a specific -Xmx.
• Do not stack collectors. Adding ZGC or Shenandoah flags on top of a G1 set gives you neither, and the JVM may refuse to start.
• Flags will not fix a leak. If the server survives one restart and dies sooner each time, no collector setting will save it — something is holding references. More heap only buys proportionally more time.

Measure before and after

The honest version: most flag changes produce a difference you cannot feel, and it is very easy to convince yourself otherwise. Use Spark to record tick times before and after, and change one thing at a time. A plausible theory about performance is worth nothing against a measurement — the time a tool in this project took to run was once "fixed" by an obviously-correct change that moved the number by 0.00 seconds.

Doing this automatically

Forge Server Doctor performs the whole procedure above — reads the report, finds the real cause under the wrappers, skips the vanilla frames, and names the mod jar. 24 failure modes, each with its fix. The free edition covers the six most common startup failures.