We are your new 5-Star Hosting Company. At least according to ★ Trustpilot

Following along with a Minecraft server? Deploy yours in minutes.

All servers come with a 24-Hour Trial, Free Backups, and 40Gbps DDoS Protection included!

Use code SAVE15 to take 15% OFF Your First Invoice with ChicagoServers! Limited Time!
Minecraft guide

Paper Global Configuration Explained: paper-global.yml Settings and Defaults

By the ChicagoServers team · Updated · 8 min read

Two of Paper's own configuration files matter most. paper-world-defaults.yml holds per-world gameplay and entity options, and paper-global.yml holds server-wide settings: how fast chunks are loaded and sent, how many players may join at once, how much packet traffic is tolerated, and how Paper behaves behind a proxy. This guide covers the second file.

It was checked on 2026-11-17 against the Paper global configuration reference. Version differences are possible, and a few options you may see mentioned in older guides are not in the current reference. Open the file your server generated and compare. For the per-world file, see the Paper world configuration guide, and for profiling before you change anything, the lag and spark guide.

Quick answer
  • The file is config/paper-global.yml, which you can open on the Files tab. Back it up, edit with spaces and not tabs, then save and restart.
  • The chunk loading limits (player-max-chunk-load-rate 100, player-max-chunk-send-rate 75, player-max-chunk-generate-rate -1) exist to protect the server from one player exploring quickly.
  • misc.max-joins-per-tick defaults to 5. Extra players are delayed, not kicked.
  • If you use a proxy, online-mode and the forwarding secret in Paper must match the proxy's settings.
  • Leave unsupported-settings alone. Paper says use them at your own risk and that they may be removed.
On this page
  1. Where the file is and how to change it
  2. Chunk loading and sending
  3. Chunk system threads
  4. Joining, auto-save and miscellaneous
  5. Packet limiter and spam limiter
  6. Behind a proxy
  7. Watchdog and console
  8. Leave these alone
  9. Frequently asked questions

Where the file is and how to change it

  1. Back up

    Take a World and settings backup on the Backups tab, or download the file from the Files tab.

  2. Open the file

    On the Files tab, open config/paper-global.yml.

  3. Change one value

    Keep the YAML indentation, using spaces and not tabs. Change one setting at a time so you know what caused any difference.

  4. Save and restart

    Save the file, then Restart. Read the Console tab for YAML errors.

Chunk loading and sending

OptionDefaultWhat it does
chunk-loading-basic.player-max-chunk-generate-rate-1.0Limits how fast chunks are generated for each player. -1 removes the limit.
chunk-loading-basic.player-max-chunk-load-rate100Limits how fast chunks are loaded for each player. -1 removes the limit.
chunk-loading-basic.player-max-chunk-send-rate75Limits chunks per second sent to each player. -1 removes the limit.
chunk-loading-advanced.auto-config-send-distancetrueMatches a client's view distance when it is lower than the server's send distance.
chunk-loading-advanced.player-max-concurrent-chunk-generates0Caps simultaneous chunk generation per player. 0 lets the server decide, -1 removes the cap.
chunk-loading-advanced.player-max-concurrent-chunk-loads0Caps simultaneous chunk loads per player. 0 lets the server decide, -1 removes the cap.

Lowering the rates protects the server when several players explore at once, at the cost of slower chunk arrival for each of them. Raising them can make new terrain appear faster for players, at a cost in CPU and bandwidth. Generating terrain is the expensive part, so pre-generating the world helps more than any rate. See the Chunky guide. View distance is a separate setting in server.properties. See the server.properties guide.

Chunk system threads

OptionDefaultWhat it does
chunk-system.io-threads-1Threads for reading and writing chunks. Any value below zero uses one thread.
chunk-system.worker-threads-1Threads for parallel chunk generation. Negative values choose automatically: one thread for three or fewer physical cores, otherwise half the physical cores.

The automatic defaults are sensible for most servers. Raise these only after profiling shows chunk work is the bottleneck, and only if the server has the CPU cores to spare.

Joining, auto-save and miscellaneous

OptionDefaultWhat it does
misc.max-joins-per-tick5Maximum players that can join per tick. Extra players are delayed, not kicked.
misc.region-file-cache-size256Maximum size of the region file cache.
misc.load-permissions-yml-before-pluginstrueLoads Bukkit's permissions.yml before plugins are enabled.
misc.use-alternative-luck-formulafalseApplies luck to items with no defined quality. Paper notes this significantly changes fishing.
misc.compression-leveldefaultResolves to -1, which means no compression.
player-auto-save.rate-1Ticks between player saves. -1 uses the autosave value from bukkit.yml.
player-auto-save.max-per-tick-1Maximum players saved per tick. -1 uses a recommended value based on rate.

If many players join in the same moment, some are held back for a few ticks because of max-joins-per-tick. They are delayed and not rejected.

Packet limiter and spam limiter

These two sections protect against clients that send too much data. They matter on public servers and can cause false kicks on modded or unusual clients, so change them carefully.

OptionDefaultWhat it does
packet-limiter.all-packets.actionKICKWhat happens when a player exceeds the limit. DROP ignores the extra packets and KICK disconnects the player.
packet-limiter.all-packets.interval7.0The measuring window in seconds.
packet-limiter.all-packets.max-packet-rate500.0Packets allowed per interval.
packet-limiter.overridesnonePer-packet overrides using the same fields. The reference gives minecraft:place_recipe as its example.
spam-limiter.incoming-packet-threshold300Packets above this threshold are ignored as spam.
spam-limiter.recipe-spam-limit20Kicks the player when reached.
spam-limiter.tab-spam-limit500Kicks the player when reached.

Behind a proxy

If your Paper server sits behind a proxy, the settings under proxies must agree with the proxy. Players then connect to the proxy and not directly to Paper, and Paper must trust what the proxy tells it about who they are.

OptionDefaultWhat it does
proxies.velocity.enabledfalseAccepts Velocity's modern forwarding.
proxies.velocity.online-modetrueMust match the proxy's setting.
proxies.velocity.secretemptyMust match the proxy's forwarding secret.
proxies.bungee-cord.online-modetrueMust match the proxy's setting.
proxies.proxy-protocolfalseProcesses PROXY Protocol messages. Unrelated to Velocity or BungeeCord.

Watchdog and console

OptionDefaultWhat it does
watchdog.early-warning-every5000 msInterval between thread dumps while the server hangs.
watchdog.early-warning-delay10000 msHow long before thread dumps start after a hang.
console.enable-brigadier-completionstrueCommand completions in the console.
console.has-all-permissionsfalseWhether the console has every permission.

The watchdog's thread dumps appear in the log when the server stops responding, and they help find what froze. Read the Console tab or logs/latest.log after a hang. See Minecraft server won't start for crash reading.

Leave these alone

unsupported-settings includes options such as allow-piston-duplication, allow-permanent-block-break-exploits, allow-headless-pistons and perform-username-validation. Paper labels them use at your own risk and says they may be removed. Several of their names describe old exploits. Keep them at their defaults unless you have a specific reason and a backup. Looking for a host? See Minecraft server hosting.

Frequently asked questions

Where is paper-global.yml?

In the config folder of your Paper server, as config/paper-global.yml. On ChicagoServers you can open it on the Files tab.

What is the difference between paper-global.yml and paper-world-defaults.yml?

paper-global.yml holds server-wide settings such as chunk loading limits, packet limits and proxy options. paper-world-defaults.yml holds per-world gameplay and entity options.

What does max-joins-per-tick do in Paper?

It limits how many players can join per tick, with a default of 5. Extra players are delayed, not kicked.

How do I use Velocity with Paper?

Enable proxies.velocity.enabled, and make online-mode and the secret match the proxy's settings. Keep the Paper server from being reachable directly.

Is it safe to change unsupported-settings in Paper?

Paper says they are use at your own risk and may be removed. Several of their names describe old exploits, so leave them at their defaults.

We are your new 5-Star Hosting Company. At least according to ★ Trustpilot

Following along with a Minecraft server? Deploy yours in minutes.

All servers come with a 24-Hour Trial, Free Backups, and 40Gbps DDoS Protection included!

We offer quality support, a detailed knowledgebase, video tutorials on most topics, and even live support in case you prefer a live human.

Use code SAVE15 to take 15% OFF Your First Invoice with ChicagoServers! Limited Time!