Minecraft Server Whitelist Guide
The simplest, strongest way to keep a friend-group server friend-group-only — how to turn it on, manage it, and the two mistakes that lock real players out by accident.
TL;DR
/whitelist onto enable it/whitelist add <name>for each player, exact spelling/whitelist listto audit who's on itenforce-whitelist=trueif you need to kick someone immediately- Edit
whitelist.jsondirectly +/whitelist reloadfor bulk changes
Step by step
1.Turn whitelist on
Either set white-list=true in server.properties and restart, or run /whitelist on from the console/in-game — the in-game command takes effect immediately, no restart needed. Existing players already connected aren't affected until they reconnect, unless you also run enforce-whitelist.
2.Add players by username
/whitelist add <username> for each player. Get the exact spelling from them directly — the server does a one-time lookup against Mojang's API to resolve the name to a UUID, so a typo adds a UUID for the wrong account (or none at all).
3.Check who's currently whitelisted
/whitelist list shows every whitelisted player. Useful before a server reset or when handing off admin duties — it's easy to lose track of who you added six months ago.
4.Remove a player
/whitelist remove <username> takes them off the list. They won't be kicked if they're already connected — only future join attempts are blocked, unless you run enforce-whitelist right after.
5.Force-kick anyone not on the list
/whitelist reload re-reads whitelist.json from disk (useful after a manual file edit). enforce-whitelist=true in server.properties goes further — it immediately disconnects any currently-online player who isn't whitelisted, the moment the list changes. This is the setting that matters if you've ever had to remove someone mid-session.
6.Bulk-edit by hand when you have a lot of names
whitelist.json sits in the server's root folder as a simple JSON array of {"uuid":..., "name":...} objects. For onboarding a big group at once, it's faster to paste a batch of entries directly into the file than run dozens of individual commands — just run /whitelist reload afterward so the server picks up the changes without a restart.
FAQ
Does whitelist stop server ops from being kicked if I change my mind?+
Not by itself — an op who gets removed from the whitelist can stay connected until they next try to rejoin, unless enforce-whitelist is true, which immediately kicks anyone online who isn't on the list. If you've ever had a griefer with op, enforce-whitelist is the panic button.
Do I need the player's exact username or their UUID?+
/whitelist add takes a username, and the server resolves it to a UUID via Mojang's API the moment you run the command (online-mode servers only). That's why a misspelled name silently adds nothing useful — always have the player confirm their exact in-game name first.
Can I whitelist Bedrock players connecting through Geyser?+
Yes, but Bedrock usernames are prefixed (commonly with a period, like .PlayerName) depending on your Floodgate config. Ask the player to try joining once first — the server console will log the exact name it saw, which you can then whitelist precisely.
What's the difference between whitelist and banning someone?+
Whitelist is an allow-list — only listed players can join at all, which is best for small friend-group servers. Bans are a block-list — anyone can join except banned players, which fits open public servers where you only want to remove specific troublemakers.
Why does whitelist add say the player isn't a valid username?+
Usually one of three things: a typo, the server is in offline-mode (cracked), where whitelist still works but resolves differently, or Mojang's API is temporarily unreachable. Double-check spelling and capitalization first — Minecraft usernames are case-sensitive for this lookup.
Whitelist management without the console
CoalHost's panel has a dedicated Players page — add and remove whitelisted players with a click, no commands to remember.
View Minecraft Hosting →