How to Whitelist Players on a Minecraft Server

01Turn the whitelist on

There are two ways to enable it, and it is worth doing both. In game (as an operator) or from the server console, run:

whitelist on

That takes effect immediately. To make sure it survives restarts and config resets, also open server.properties in the server folder and set:

white-list=true

Note the hyphen — the property is white-list, not whitelist. Changes to server.properties only load on restart, which is why the in-game command is handy for switching it on right now.

02Add players with /whitelist add

For each player who should be allowed in:

whitelist add PlayerName

Use their exact current Minecraft username (capitalisation does not matter, spelling does). The server looks the name up against Mojang, resolves it to the account's permanent UUID, and stores both in whitelist.json. Because the UUID is what actually gets stored, a whitelisted player who later changes their username stays whitelisted.

This lookup is also why you cannot whitelist a player who has never bought the game, and why offline-mode (cracked) servers have a harder time — without Mojang authentication the server generates offline UUIDs from names, so entries only match if added while the server is in the same mode.

03Remove players and list who is whitelisted

whitelist remove PlayerName
whitelist list

whitelist list prints everyone currently allowed. You can also edit whitelist.json directly — useful for bulk adds — but the server only reads it at boot or when you run whitelist reload, so run that command after hand-editing or your changes will silently do nothing.

04Decide whether to enforce the whitelist

By default, removing someone from the whitelist stops their next login but does not kick them if they are already online. If you want removal to take effect instantly, set this in server.properties:

enforce-whitelist=true

With enforcement on, running whitelist reload (or removing a player) immediately kicks anyone online who is not on the list. Operators are exempt from the whitelist check, so your own account will never lock itself out as long as it is opped.

05Give trusted players operator status if needed

The whitelist controls who can join; it grants no powers. Players who should be able to run admin commands — including /whitelist add for inviting others — need operator status:

op PlayerName
deop PlayerName

Hand out op sparingly: level-4 operators (the default) can run every command on the server, including /stop. For a friends server, one or two ops is plenty; on anything bigger, use a permissions plugin instead.

Run it on HostPanel: on our Minecraft server hosting plans the console and server.properties editor are both one click away in the panel, so you can whitelist friends without touching a terminal.

Troubleshooting

“That player does not exist” when adding a name

The username is misspelled, the player has renamed themselves, or the server cannot reach Mojang's authentication servers. Check the spelling on the player's launcher profile, and if Mojang's session services are having an outage, wait and retry.

A whitelisted player still gets “You are not white-listed on this server!”

Usually a Java vs Bedrock mismatch: Bedrock players joining through Geyser/Floodgate get a prefixed gamertag (often starting with . or *) and a different UUID, so whitelist the prefixed name, not the plain gamertag. Otherwise, the entry was probably added to whitelist.json by hand without a whitelist reload.

The whitelist turns itself off after a restart

You enabled it with the command but server.properties still says white-list=false, and something (often a panel or a config sync) rewrote the runtime state at boot. Set white-list=true in the file and restart to make it stick.