A whitelist limits who can join your Java Edition server. Vanilla stores the list in whitelist.json next to server.properties. Getting UUIDs wrong — especially on offline-mode networks — is the most common reason players suddenly cannot join.
Generate the file — paste names into the Whitelist Creator for online Mojang UUIDs or offline-mode hashes, then download whitelist.json or copy /whitelist add commands. Validate plugin YAML with the YAML Validator.
Section 01
What format does whitelist.json use?
Vanilla Java Edition expects a JSON array of objects with uuid and name:
[
{
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
"name": "Notch"
}
]You can maintain the file by hand, generate it with a tool, or add players live with /whitelist add <player> (which updates the file when the server can resolve the name).
Section 02
Online vs offline mode
Match UUID generation to online-mode in server.properties (or your proxy’s forwarding mode):
- Online mode (
online-mode=true) — UUIDs come from Mojang/Microsoft accounts and stay stable across renames. - Offline mode (
online-mode=false) — UUIDs are derived fromOfflinePlayer:<name>. A rename creates a completely different UUID, so update the whitelist when names change.
On Velocity / BungeeCord networks, the backend’s effective UUID mode must match how players authenticate through the proxy. Mixed modes cause “invalid session” or whitelist misses.
Section 03
Install and enable the whitelist
- Download or write
whitelist.json. - Place it in the server root next to
server.properties. - Set
white-list=true(and keeponline-modeconsistent with how you generated UUIDs). - Restart the server, or run
/whitelist reloadif you only changed the file. - Confirm with
/whitelist listand a test join from an allowed account.
Always keep at least one operator account able to join — or console access — before enabling the whitelist, so you cannot lock yourself out.
Section 04
Validate related configs
Whitelist problems often sit beside broken YAML in permission or auth plugins. After editing plugin configs:
- Run them through the YAML Validator to catch indentation and syntax errors.
- Reload the specific plugin or restart if the plugin does not hot-reload safely.
- Check console for UUID / auth warnings on join attempts.
FAQ
Frequently asked questions
Where does whitelist.json go?
Place whitelist.json in the server root next to server.properties. Set white-list=true, then restart or run /whitelist reload.
Online mode vs offline mode UUIDs?
Online mode uses Mojang/Microsoft account UUIDs. Offline mode derives UUIDs from the player name, so a rename creates a different UUID.