Configuration

How the config directory is laid out, how files are generated, upgraded and reloaded, and what happens when one is wrong.

Files
Generation
Upgrades
Reloading
When a file is wrong

All configuration lives in config/, next to the binary, as TOML files with one file per domain. A file is a domain of its own, not one more table in an existing file.

Configuration is what you write. State is what the server writes (player data, group membership, the whitelist, the API token), and it never goes in config/. See Installation for where state lives.

Files#

File	Domain	Reference
`server.toml`	Network, players, performance, plugins, data packs, logging	Server settings
`limits.toml`	Packet rate limits, spam kicks, item text caps	Server settings
`worlds.toml`	Which worlds load, and the defaults every world inherits	Worlds
`worlds/mobs.toml`	Mob caps, spawning, despawning and per-type tweaks, inherited by every world	Worlds
`groups.toml`	Permission groups and operators	Groups and permissions
`commands.toml`	Command permissions, aliases and wording	Commands
`messages.toml`	What players are told when turned away or removed	Interface
`server_list.toml`	The multiplayer list entry: MOTD, icon, player count	Interface
`tab_list.toml`	The panel behind Tab	Interface
`scoreboard.toml`	The sidebar	Interface
`boss_bar.toml`	The bar across the top	Interface
`animations.toml`	Text that moves, shared by the files above	Interface

Each world also carries its own settings.toml and mobs.toml inside worlds/<name>/, which inherit from the two world files above. See Worlds.

Some features are tables of server.toml rather than files of their own: the management API and RCON ([network.rcon], [network.api]), proxy forwarding ([network.forwarding]) and the client version window (backwards, future-protocols, snapshots and name-substitutes under [network.java], protocols and future-protocols under [network.bedrock]). They are documented with the feature they belong to, not in the key reference.

Generation#

Every file is created on the first start with vanilla's values and a comment per option. A file that already exists is never overwritten. The comments mark each option that changes behaviour compared with vanilla as NO VANILLA or NOT VANILLA, and all of those ship disabled.

server.toml is created from your server.properties if there is one and no config/server.toml yet; see Installation.

Upgrades#

When an update adds options to server.toml, limits.toml, messages.toml, worlds.toml or commands.toml, the server appends them to the end of your file, commented out, with their defaults and explanations:

toml

# ---- Options added in Basalt 26.3, commented out with their defaults. Remove the leading # to change one. ----

# [server]
# Seconds with nobody online before the server stops ticking...
# pause-when-empty-seconds = 60

The log names the keys it added. Your own values and comments are never touched, and nothing changes behaviour until you uncomment an option.

Reloading#

/reload re-reads the files that can change while the server runs and swaps them in as one unit:

groups.toml, server_list.toml, commands.toml, animations.toml, tab_list.toml, scoreboard.toml, boss_bar.toml, limits.toml and messages.toml.

server.toml, worlds.toml, every settings.toml and mobs.toml are read when the server starts or a world loads, so a change to them needs a restart. The log says so after a reload. /reload also rescans the data packs.

If any reloadable file is invalid, nothing is swapped: the server keeps the configuration it had and reports Configuration not reloaded with the reason.

When a file is wrong#

A malformed file never starts the server quietly on defaults, because a server running on values you did not choose is worse than one that did not start.

At startup, an unreadable or invalid file stops the start with exit code 2. The log names the file and the key, for example config/server.toml: max-world-size must be between 1 and 29999984. Fix it and start again.
On /reload, the previous configuration stays active (see above).
A world's own settings.toml or mobs.toml is the exception: the world keeps the inherited defaults and the log warns with the reason, so one world's typo does not stop the server.

Both editions switched off in server.toml, no world declared, or more than one default world, stop the start too; see Worlds.

Edit this page