How to Create and Install Minecraft whitelist.json

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 from OfflinePlayer:<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 keep online-mode consistent with how you generated UUIDs).
Restart the server, or run /whitelist reload if you only changed the file.
Confirm with /whitelist list and 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.