Minecraft Server Thread Optimization: How to Configure Paper's Thread Pool and Reduce Main Thread Bottlenecks

# Minecraft Server Thread Optimization: How to Configure Paper's Thread Pool and Reduce Main Thread Bottlenecks

One of the most misunderstood aspects of Minecraft server performance is threading. Most server admins blame plugins or entity counts when their TPS drops — but often, the real bottleneck is how work is distributed across CPU threads. Understanding and configuring your server's thread model can unlock significant performance gains, especially on servers with 4+ CPU cores.

This guide covers Paper's thread pool settings, where the main thread becomes a bottleneck, and how next-generation forks like Folia and Pufferfish tackle the problem differently.

---

Why Minecraft's Main Thread Is a Problem

Vanilla Minecraft (and most server software based on it) runs almost all game logic on a single main thread. This includes:

• Mob AI and pathfinding
• Redstone updates
• Block physics
• Player movement processing
• Plugin event handling

Because all of this runs sequentially on one thread, a single expensive operation — like a laggy plugin event or a complex mob pathfinding task — can delay *everything* else. This is the root cause of most TPS drops.

Your server might be running on a 16-core CPU, but if 15 of those cores are idle while the main thread is overloaded, you're wasting hardware.

---

Paper's Worker Thread Pool

Paper offloads several tasks from the main thread onto a background worker thread pool. These include:

• Chunk loading and saving
• World generation
• Lighting engine calculations
• Some async I/O operations

You can configure the size of this worker pool in config/paper-global.yml (Paper 1.19+):

chunk-system:
  worker-threads: -1

The default value of -1 lets Paper automatically calculate the number of worker threads based on your available CPU cores. However, manually tuning this value can help depending on your workload:

• Shared hosting (2–4 cores): Set worker-threads: 2 to avoid resource contention with the main thread.
• Dedicated servers (8+ cores): Try worker-threads: 6 or higher. Leave at least 2 cores for the main thread and OS tasks.
• Heavy world generation: Increase to worker-threads: 8 temporarily during pre-generation, then reduce afterward.

Restart your server after each change and monitor TPS and chunk load times.

---

Async Chunk Loading: The Game Changer

Paper's async chunk system (introduced in 1.18 and significantly improved in 1.19–1.20) moves chunk loading entirely off the main thread. This means players flying around or teleporting no longer spike main-thread CPU usage the way they once did.

To ensure you're getting the most from this system, make sure these values in paper-world.yml are properly set:

chunks:
  auto-save-interval: 6000
  delay-chunk-unloads-by: 10s
  entity-per-chunk-save-limit:
    experience_orb: 16
    snowball: 8
    arrow: 16

Keep auto-save-interval at 6000 (5 minutes) — saving too frequently forces constant disk I/O and chunk serialization, both of which consume worker thread time.

---

Identifying Main Thread Bottlenecks with Spark

Before tuning thread counts, you need to identify where your main thread is spending time. The [Spark profiler](https://spark.lucko.me/) is the best tool for this.

Run a profile with:

/spark profiler --only-ticks-over 50

This captures only tick overruns — the ticks that actually cause lag. Look for:

• Plugin event handlers taking >5ms per tick
• Entity AI (PathfinderGoal classes) consuming large percentages
• Block physics or ServerLevel.tickChunk dominating the flame graph

If your flame graph shows chunk I/O or lighting on the main thread, you may be running an outdated version of Paper. Update to the latest build.

---

Folia: True Multithreading for Large Servers

[Folia](https://github.com/PaperMC/Folia) is PaperMC's experimental regionalized multithreading fork. Instead of one main thread, Folia splits the world into independent regions, each ticked on its own thread simultaneously.

This is fundamentally different from standard Paper — Folia can genuinely use multiple CPU cores for game logic. The tradeoff:

• Most plugins are not Folia-compatible without code changes
• Region boundaries introduce complexity for cross-region interactions
• Best suited for large, spread-out player populations (100+ players across a big map)

For servers running vanilla-like gameplay or plugins that have been updated for Folia (EssentialsX, LuckPerms, etc.), Folia can provide a massive TPS improvement under load.

Check plugin compatibility before migrating: look for the folia-supported: true tag in plugin.yml.

---

Pufferfish: Smarter Thread Usage Without Breaking Plugins

[Pufferfish](https://github.com/pufferfish-gg/Pufferfish) is a Paper fork focused on performance improvements that work *within* the standard threading model. Key features relevant to threading:

• DABS (Dynamic Activation of Brain System): Reduces how often mob AI ticks based on distance from players. This directly cuts main-thread CPU load from pathfinding.
• Async entity tracking: Moves some entity tracking off the main thread.

In pufferfish.yml:

dab:
  enabled: true
  start-distance: 12
  max-tick-freq: 20
  activation-dist-mod: 8

DABS alone can reduce mob AI overhead by 30–60% on servers with large mob farms or high entity counts — without the plugin-compatibility headaches of Folia.

---

Practical Thread Optimization Checklist

Here's a quick checklist for thread-related optimizations:

• [ ] Update to the latest Paper build for best async chunk performance
• [ ] Set worker-threads based on your CPU core count (not just leave at -1)
• [ ] Profile with /spark profiler --only-ticks-over 50 before making changes
• [ ] Use Pufferfish for DABS if mob AI dominates your main thread
• [ ] Evaluate Folia only if you have 100+ players and Folia-compatible plugins
• [ ] Avoid plugins that run heavy synchronous logic in main-thread events
• [ ] Keep auto-save intervals reasonable to avoid worker thread I/O spikes

---

Monitor Threads Continuously

Thread behavior changes as your player count grows and your world expands. What works at 20 players may bottleneck at 80. Tools like [PulseNode](https://pulsenode.tech) can track your server's TPS trends and alert you when performance degrades — so you can catch thread bottlenecks before your players notice lag.

---

Final Thoughts

Thread optimization isn't a one-time fix — it's an ongoing process of profiling, adjusting, and validating. Start by profiling with Spark to understand where your main thread is actually spending time. Then tune Paper's worker pool, consider Pufferfish's DABS for mob AI, and evaluate Folia if you're running a large network that demands true multithreading.

The goal is simple: keep your main thread as free as possible so it can do what it absolutely must — and delegate everything else.