Skip to main content
Paper’s global configuration file contains server-wide settings that affect all worlds. This file is located at config/paper-global.yml and provides advanced features beyond vanilla Minecraft.

​
Location

server-root/
└── config/
    └── paper-global.yml

​
Configuration Reference

​
Chunk Loading

​
chunk-loading-basic.player-max-chunk-send-rate
double
default:"75.0"
Maximum rate in chunks per second that the server will send to any individual player. Set to -1 to disable.
Lower values reduce bandwidth and CPU usage for players with slow connections.
​
chunk-loading-basic.player-max-chunk-load-rate
double
default:"100.0"
Maximum rate at which chunks will load for any individual player. This affects chunk generation since a chunk load is issued first to test if a chunk exists. Set to -1 to disable.
​
chunk-loading-basic.player-max-chunk-generate-rate
double
default:"-1.0"
Maximum rate at which chunks will generate for any individual player. Set to -1 to disable this limit.
Limiting generation can prevent lag spikes when players explore new areas.
​
chunk-loading-advanced.auto-config-send-distance
boolean
default:"true"
If true, the server will match the chunk send radius that clients have configured in their view distance settings if the client’s setting is less than the server’s send distance.
​
chunk-loading-advanced.player-max-concurrent-chunk-loads
integer
default:"0"
Maximum amount of concurrent chunk loads per player. Set to 0 to let the server configure it automatically per player, or -1 to disable the limit.
​
chunk-loading-advanced.player-max-concurrent-chunk-generates
integer
default:"0"
Maximum amount of concurrent chunk generations per player. Set to 0 for automatic configuration, or -1 to disable.

​
Messages

​
messages.kick.authentication-servers-down
Component
default:"multiplayer.disconnect.authservers_down"
Message shown when authentication servers are unavailable.
​
messages.kick.connection-throttle
Component
Message shown when a player is connecting too frequently.
​
messages.kick.flying-player
Component
default:"multiplayer.disconnect.flying"
Message shown when a player is kicked for flying without permission.
​
messages.no-permission
Component
Default message shown when a player lacks permission for a command.
​
messages.use-display-name-in-quit-message
boolean
default:"false"
Use player display names instead of usernames in quit messages.

​
Proxies

​
proxies.bungee-cord.online-mode
boolean
default:"true"
Whether BungeeCord proxy handles authentication.
Ensure your server is properly firewalled when using BungeeCord mode!
​
proxies.velocity.enabled
boolean
default:"false"
Enable Velocity modern forwarding support.
​
proxies.velocity.online-mode
boolean
default:"true"
Whether Velocity proxy handles authentication.
​
proxies.velocity.secret
string
default:""
The secret key from your Velocity configuration. Can also be set via the PAPER_VELOCITY_SECRET environment variable.
This secret must match your Velocity proxy configuration exactly!
​
proxies.proxy-protocol
boolean
default:"false"
Enable HAProxy PROXY protocol support.

​
Performance

​
chunk-system.io-threads
integer
default:"-1"
Number of I/O threads for chunk operations. -1 uses the default calculated value.
Let Paper auto-configure this unless you have specific performance requirements.
​
chunk-system.worker-threads
integer
default:"-1"
Number of worker threads for chunk processing. -1 uses the default calculated value.
​
player-auto-save.rate
integer
default:"-1"
How often (in ticks) player data should be saved. -1 uses Minecraft’s default (6000 ticks/5 minutes).
​
player-auto-save.max-per-tick
integer
default:"-1"
Maximum number of players to save per tick. Automatically calculated if set to -1.

​
Console

​
console.enable-brigadier-highlighting
boolean
default:"true"
Enable syntax highlighting in the console for commands.
​
console.enable-brigadier-completions
boolean
default:"true"
Enable tab completions in the console using Brigadier.
​
console.has-all-permissions
boolean
default:"false"
Whether the console should have all permissions by default.

​
Spam Limiter

​
spam-limiter.tab-spam-increment
integer
default:"1"
Amount to increment spam counter for tab completion requests.
​
spam-limiter.tab-spam-limit
integer
default:"500"
Maximum tab completion spam counter before action is taken.
​
spam-limiter.recipe-spam-increment
integer
default:"1"
Amount to increment spam counter for recipe requests.
​
spam-limiter.recipe-spam-limit
integer
default:"20"
Maximum recipe spam counter before action is taken.
​
spam-limiter.incoming-packet-threshold
integer
default:"300"
Maximum incoming packet rate before throttling. Set to -1 to disable.

​
Commands

​
commands.suggest-player-names-when-null-tab-completions
boolean
default:"true"
Suggest online player names when a command has no tab completions.
​
commands.time-command-affects-all-worlds
boolean
default:"false"
Whether the /time command changes time in all worlds or just the executor’s world.
​
commands.ride-command-allow-player-as-vehicle
boolean
default:"false"
Allow mounting entities to a player in the vanilla /ride command.

​
Item Validation

​
item-validation.display-name
integer
default:"8192"
Maximum character length for item display names.
​
item-validation.lore-line
integer
default:"8192"
Maximum character length for each line of item lore.
​
item-validation.book.title
integer
default:"8192"
Maximum character length for book titles.
​
item-validation.book.author
integer
default:"8192"
Maximum character length for book authors.
​
item-validation.book.page
integer
default:"16384"
Maximum character length for book pages.
​
item-validation.book-size.page-max
integer
default:"2560"
Maximum number of pages in a book. Set to -1 to disable.
​
item-validation.book-size.total-multiplier
double
default:"0.98"
Multiplier for total book size validation.
​
item-validation.resolve-selectors-in-books
boolean
default:"false"
Whether to resolve entity selectors in book text.
Enabling this can have security implications!

​
Watchdog

​
watchdog.early-warning-every
integer
default:"5000"
Interval in milliseconds between watchdog early warnings.
​
watchdog.early-warning-delay
integer
default:"10000"
Delay in milliseconds before the watchdog starts issuing warnings.

​
Miscellaneous

​
spark.enabled
boolean
default:"true"
Enable the built-in Spark profiler.
​
spark.enable-immediately
boolean
default:"false"
Enable Spark immediately on server startup.
​
collisions.enable-player-collisions
boolean
default:"true"
Enable player-to-player collisions.
​
collisions.send-full-pos-for-hard-colliding-entities
boolean
default:"true"
Send full position updates for entities with hard collisions.
​
scoreboards.track-plugin-scoreboards
boolean
default:"false"
Track scoreboards created by plugins in /paper dumpplugins.
​
scoreboards.save-empty-scoreboard-teams
boolean
default:"true"
Save scoreboard teams even when they have no members.
​
logging.deobfuscate-stacktraces
boolean
default:"true"
Deobfuscate stacktraces to readable Mojang mappings.
This makes error messages much easier to understand!
​
misc.region-file-cache-size
integer
default:"256"
Number of region files to keep cached. Minimum value is 4.
​
misc.use-alternative-luck-formula
boolean
default:"false"
Use an alternative luck formula. See https://luckformula.emc.gs for details.
​
misc.load-permissions-yml-before-plugins
boolean
default:"true"
Load permissions.yml before plugins are enabled.
​
misc.enable-nether
boolean
default:"true"
Whether the nether dimension is enabled and will be loaded.

​
Block Updates

​
block-updates.disable-noteblock-updates
boolean
default:"false"
Disable note block updates for redstone contraptions.
​
block-updates.disable-tripwire-updates
boolean
default:"false"
Disable tripwire updates.
​
block-updates.disable-chorus-plant-updates
boolean
default:"false"
Disable chorus plant updates.
​
block-updates.disable-mushroom-block-updates
boolean
default:"false"
Disable mushroom block updates.

​
Example Configuration

chunk-loading-basic:
  player-max-chunk-send-rate: 75.0
  player-max-chunk-load-rate: 100.0
  player-max-chunk-generate-rate: -1.0

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "your-secret-here"

chunk-system:
  io-threads: -1
  worker-threads: -1

console:
  enable-brigadier-highlighting: true
  enable-brigadier-completions: true

spark:
  enabled: true

logging:
  deobfuscate-stacktraces: true

World Configuration

Per-world specific settings

Performance Tuning

Optimize your server performance
Changes to paper-global.yml require a server restart or use the /paper reload command. Some settings may require a full restart.

Build docs developers (and LLMs) love

Get started for freeTalk to us