Is your Paper server stuttering? This guide shows you how to find the cause and fix it deliberately – instead of blindly changing values. For simply looking up what a config option means, see the reference article Paper configuration explained.
Understanding TPS and MSPT
- TPS (Ticks per Second): how often the server calculates the world per second. 20 = target. From 19 it's noticeable, below 15 it's critical.
- MSPT (Milliseconds per Tick): how long one tick takes. This is the more meaningful number. At 20 TPS you have 50 ms per tick – target: consistently under 50 ms, ideally under 35 ms.
Measure TPS/MSPT with /tps, /mspt and – most informative – the Spark plugin.
Diagnose first, then configure
This is the most important section. First measure where the time goes – don't guess.
- Install Spark (plugin)
- Start the profiler:
/spark profiler start, let it run under load for a few minutes - Stop with
/spark profiler stop– you get a link with a detailed report - Read off which systems eat the time (entities, chunks, redstone, plugins, hoppers)
- For sudden stutters:
/spark tickmonitorshows lag spikes - Alternatively: the classic timings report
Important
Rule of thumb: Config tuning gains 2–5 TPS – one broken plugin costs 15. Tweaking the config without diagnosis often optimizes the wrong thing.
Lag causes by category
| Category | Typical cause |
|---|---|
| Memory / JVM | Too little RAM or missing/wrong JVM flags (Aikar's Flags) |
| Java version | Wrong Java version for the Minecraft version |
| View distance | view-distance / simulation-distance too high |
| Entities | Mob farms, dropped items lying around, boats/minecarts in bulk |
| Chunks | Players constantly generating new chunks with Elytra |
| Redstone | Redstone clocks, long hopper chains |
| Plugins | Too many or badly written plugins |
| Hardware | HDD instead of SSD, oversold/shared hardware |
| Network | Network lag ≠ server lag: high ping with good TPS = network, not the server |
Info
Ping and TPS are two different things. A high ping with stable 20 TPS is a connection problem (routing, Wi-Fi, distance) – not server lag.
Concrete config recommendations
The following levers tend to help most. For each: what it costs in gameplay – stated honestly. The full explanation of every key is in the reference article.
| Setting (file) | Recommendation | Gameplay cost |
|---|---|---|
view-distance / simulation-distance (server.properties) | Match to player count, e.g. view 8, simulation 6 | Slightly shorter view; barely noticeable |
redstone-implementation (paper) | ALTERNATE_CURRENT | None – faster, compatible redstone engine |
per-player-mob-spawns (paper) | true | None noticeable; fairer mob distribution |
tick-rates.behavior.villager / sensor.villager (paper) | Increase the values (tick less often) | Villagers react slightly slower |
max-auto-save-chunks-per-tick (paper) | Lower it | Saving spreads out; slightly higher data-loss risk on a crash |
despawn-ranges (paper) | Reduce | Mobs despawn a bit sooner in the distance |
entity-activation-range (spigot.yml) | Lower per mob type | Distant mobs "sleep" sooner; mind your farms |
merge-radius (spigot.yml) | Increase for items/XP orbs | Drops/orbs merge more generously |
max-entity-collisions (paper) | Lower (e.g. 2) | Less push physics with mob crowds |
hopper.disable-move-event (paper) | true | ⚠️ Can break hopper-dependent plugins |
Caution
hopper.disable-move-event: true saves noticeable performance but suppresses the InventoryMoveItemEvent. Plugins that react to hopper movement (some shop/sorting plugins) will stop working. Check first.JVM & hardware
- Use Aikar's Flags – but understand them, don't just slap them on: they tune the G1 garbage collector so that lag spikes from GC pauses are minimized. The full flag set is in Optimizing Minecraft server performance.
- RAM: more is not automatically better. Too much heap lengthens GC pauses. Allocate as much as the server realistically needs (
-Xms=-Xmx). - CPU: Minecraft is mostly single-threaded – the main tick runs on one core. Single-core performance beats core count. A fast 4-core beats a slow 16-core.
- Pick the Java version to match the Minecraft version (current versions need Java 21).
Tip
On shared/oversold hardware, no config trick helps if the CPU power simply isn't there. A server with guaranteed, strong single-core performance is the foundation – it's worth looking at a more powerful game server.
Plugin hygiene
- When suspicious: disable plugins one by one and watch the TPS to pin down the culprit
- Typical performance hogs: Dynmap (rendering), heavy protection/world-management plugins
- Spark is a must for diagnosis; judge ClearLag & co. critically – they often just mask symptoms
- Beware "optimization" plugins that noticeably add load themselves
What does NOT help
- Blindly raising RAM – past a point, more heap actually hurts through longer GC pauses
- Copying random configs from YouTube videos – often outdated, for other versions, or applied blindly
- A chunk cleaner as a permanent solution – it fights symptoms, not the cause; better find the source of the entities
Quick checklist
- Measure with
/spark profiler– don't guess - Rule out plugins (disable one by one)
- Java 21 + Aikar's Flags,
-Xms=-Xmx - Match
view-/simulation-distanceto player count redstone-implementation: ALTERNATE_CURRENT,per-player-mob-spawns: true- Villager tick rates up,
max-auto-save-chunks-per-tickdown,despawn-rangesdown - Only then think about fine-tuning
Where to next
- Full options reference: Paper configuration explained
- JVM flags & basics: Optimizing Minecraft server performance
- No server of your own yet? How to create a Minecraft server