Reference

Minecraft whitelist.json: schema, UUID lookups, and enforce-whitelist

Schema for whitelist.json, how to look up player UUIDs, when to edit by hand versus the in game command, and what enforce-whitelist actually does at runtime.

6 min readMinecraftServer adminVerified Jun 4, 2026

whitelist.json is the single source of truth for who can join a Minecraft Java Edition server when whitelisting is on. The file lives in the server root, is rewritten by the server any time a /whitelist command runs, and is read fresh every time a connection attempt arrives.

Schema

A JSON array of objects, one per player. Two required fields, no optional fields in vanilla.

whitelist.json

$[
$  {
$    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
$    "name": "Notch"
$  },
$  {
$    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
$    "name": "jeb_"
$  }
$]

Field	Type	Notes
`uuid`	string	Dashed UUID v4 from the Mojang API. Always required.
`name`	string	Current username. Refreshed automatically by the server when the player joins.

Looking up UUIDs

Use the public Mojang API. USERNAME is case insensitive.

user@host

$curl -s https://api.mojang.com/users/profiles/minecraft/Notch
$# {"id":"069a79f444e94726a5befca90e38aaf5","name":"Notch"}

The API returns the UUID without dashes. Insert dashes at positions 8, 12, 16, and 20 before pasting intowhitelist.json. Most online converters do this in one click; ten-online-tools.com and namemc.com both work.

In game command versus hand edit

Both paths work. Use the command when the server is running and you can issue commands from console or RCON. Edit by hand when restoring a backup, syncing a list across multiple servers, or scripting a CI flow.

Action	Command	Notes
Enable whitelisting	`/whitelist on`	Equivalent to white-list=true in server.properties.
Add player	`/whitelist add Notch`	Resolves the UUID via Mojang and appends to the file.
Remove player	`/whitelist remove Notch`	Removes the entry. Does not kick if enforce-whitelist is false.
Reload from disk	`/whitelist reload`	Read whitelist.json again. Required after hand edits.

enforce-whitelist behavior

Two related keys in server.properties control whitelist behavior:

white-list=true activates the gate at all. With this off, whitelist.json is read but never consulted.
enforce-whitelist=true makes whitelist changes retroactive. Removing a player kicks them immediately, even mid session. Default is false, which only applies on the next login.

Migrating from white-list.txt

Servers older than 1.7.6 used a plain text file,white-list.txt, with one username per line. To migrate, upgrade the server jar and run it once. On startup the server reads the old text file, resolves each username to a UUID via Mojang, writes the modern whitelist.json, and renames the old file to white-list.txt.converted. Keep that file as a backup until you confirm the new list looks right.

Frequently asked questions

What is the difference between whitelist.json and ops.json?

whitelist.json controls who is allowed to join. ops.json controls who has operator permissions. A player can be on one without being on the other, and most public servers keep them strictly separated.

How do I look up a Minecraft player UUID?

Query the Mojang API: https://api.mojang.com/users/profiles/minecraft/USERNAME returns the current UUID. Sites like namemc.com expose the same data through a UI. Always insert the dashed form into whitelist.json.

Does whitelist.json work on a cracked server?

Only weakly. On an offline mode server, UUIDs are generated locally from the username, so anyone who knows a whitelisted username can join. Whitelisting on offline mode servers is a hint, not a security boundary.

What does enforce-whitelist do?

When true, editing the whitelist (by hand or via the /whitelist command) immediately kicks any online player who is not on the new list. When false, changes only apply to new joins; players already in the world keep their session until they disconnect.

All references