A whitelist is the simplest way to make a Minecraft server private: a list of allowed accounts, and everyone else is turned away at the door. It takes one command to switch on. What confuses people is the behaviour around the edges, because a whitelist does not remove players who are already connected, it does not apply to operators, and there is a second setting called enforce-whitelist that most people have never heard of and which changes what happens when you edit the list. This guide covers turning it on properly, adding players, and each of the reasons someone gets in when you thought they could not.
Turning the Whitelist On
Three commands do almost everything. Run them from the server console without a leading slash, or in game as an operator with one.
| Command | What it does |
|---|---|
whitelist on | Turns the whitelist on |
whitelist off | Turns it off |
whitelist add <player> | Adds a player to the list |
whitelist remove <player> | Removes them |
whitelist list | Shows everyone currently whitelisted |
whitelist reload | Re-reads whitelist.json from disk |
- Open your server in the LoafHub panel and go to the Console tab
- Run
whitelist addfor each player you want to allow - Run
whitelist on - Run
whitelist listto confirm the list is what you expect
Turning the whitelist on does not disconnect anyone already playing. It only affects new connections, so an uninvited player who is already online stays online until they leave or you remove them.
Warning:
whitelist ondoes not kick anyone already connected. Kick them separately if you need them gone nowTip: Add yourself before turning it on, otherwise you lock yourself out on your next join
Doing It Without Commands
On Loafhosts the Player Manager in your server’s sidebar has a Whitelist tab showing everyone on the list with a count, and lets you add and remove players by clicking rather than typing. It also has a toggle for the whitelist itself, so you can switch enforcement on and off from the same page.
The list is read from whitelist.json, which means the tab still shows you the whitelist while the server is stopped. Adding or removing a player does need the server running, because that action goes through the server console.
Tip: The Whitelist tab reads the file, so you can review who is allowed even with the server off
Note: The panel sends these through the console pipe, so no RCON setup is required
The Setting Almost Nobody Knows About
There is a second option in server.properties called enforce-whitelist, and it is set to false by default.
With it off, the whitelist is checked when a player connects and that is all. If you remove someone from the whitelist while they are playing, nothing happens to them. They keep playing until they disconnect.
With enforce-whitelist=true, the server enforces the list against connected players too, so removing someone kicks them immediately. Reloading the whitelist also drops anyone no longer on it.
| Setting | Removing a player mid-session |
|---|---|
enforce-whitelist=false (default) | They keep playing until they leave |
enforce-whitelist=true | They are kicked straight away |
Set it in Config Editor in the panel, or with server.properties directly, then restart. This is the answer to “I removed them from the whitelist and they are still on my server”.
Note:
enforce-whitelistisfalseby default, which is why removing someone does not kick themWarning: This is a
server.propertiesvalue, so it needs a restart. It is not a live command
Operators Bypass the Whitelist
The second reason someone gets in is simpler and catches people out just as often. Operators are not subject to the whitelist. An op can connect whether or not they are on the list.
That is intentional, so an admin cannot lock themselves out of their own server. It does mean that if you opped someone months ago and forgot, removing them from the whitelist achieves nothing. Check ops.json, or the Operators tab in the Player Manager, and deop anyone who should not have that access.
Warning: Op status overrides the whitelist entirely. Check your operator list when someone gets in that should not
Tip: The Operators tab shows exactly who has op. Treat that list as seriously as your whitelist
Where the Whitelist Is Stored
The list lives in whitelist.json in your server root, as an array of entries with a UUID and a name.
[
{
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
"name": "Notch"
}
]
The UUID is what actually matters. Because entries are keyed on the account rather than the name, a player who changes their Minecraft username stays whitelisted automatically.
You can edit this file in the File Manager, but run whitelist reload afterwards, or the server keeps using the copy it holds in memory and your edit appears to do nothing.
Warning: Keep the JSON valid when editing by hand. A malformed file can result in an empty whitelist
Tip: After editing the file directly, run
whitelist reloadso the server picks it up
Offline Mode Changes the Rules
On a server running in offline mode, UUIDs are generated from the username rather than issued by a Mojang account. Two consequences follow.
First, a whitelisted player who changes their name becomes a different account as far as the server is concerned, and loses access. Second, the whitelist is much weaker as a security control, because nothing verifies that a connecting player owns the name they are using.
If your server is offline mode and you are relying on a whitelist to keep people out, understand that it is a convenience rather than a real barrier.
Warning: On an offline-mode server a whitelist does not verify identity, because usernames are not authenticated
Note: Name changes break offline-mode whitelist entries, since the UUID is derived from the name
Whitelist, Ban, or Neither
They solve different problems and it is worth being deliberate.
| Approach | Best for |
|---|---|
| Whitelist | A private server for a known group. Everyone is blocked unless invited |
| Bans | A public server. Everyone is allowed unless removed |
| Neither | A genuinely open server, which needs active moderation instead |
A whitelist scales badly for a public server and is close to perfect for a friends server. Bans are the opposite.
Tip: For a server that is public but troubled, a whitelist is a good temporary measure while you deal with a problem
Frequently Asked Questions
How do I whitelist someone on my Minecraft server?
Run whitelist add <player> from the server console, then whitelist on if the whitelist is not already active. On Loafhosts you can also open Player Manager in your server’s sidebar and use the Whitelist tab to add players by clicking.
Why can players still join when the whitelist is on?
Two usual reasons. They are a server operator, and ops bypass the whitelist entirely, so check your operator list. Or they were already connected when you turned it on, since the whitelist is only checked on connection.
I removed someone from the whitelist and they are still playing
That is the default behaviour. Set enforce-whitelist=true in server.properties and restart, which makes the server enforce the whitelist against connected players and kick anyone removed from it.
What does enforce-whitelist actually do?
With it off, the default, the whitelist is only checked when a player connects. With it on, the server also enforces the list against players already online, so removing someone or reloading the whitelist disconnects them immediately.
Where is the whitelist stored on a Minecraft server?
In whitelist.json in your server root, as a list of UUID and name pairs. Because entries are keyed on UUID, a whitelisted player keeps access after a username change on an online-mode server.
Does the whitelist work on modded servers?
Yes. It is a vanilla server feature, so it works on Forge, NeoForge, Fabric, Quilt, and every Bukkit derivative. The file location and commands are the same.
Do I need to restart to change the whitelist?
No for adding and removing players, since those take effect immediately. Yes for enforce-whitelist, because that is a server.properties setting read at startup.