Short answer
Set white-list=true in server.properties, restart, and add each player with /whitelist add TheirName. A player who is not on the list is refused at the handshake with "You are not white-listed on this server".
The whitelist is the difference between a private world and a public one that hopes nobody finds the address. It refuses unknown players before they load the world, which matters for a server where the world is the thing worth protecting.
This guide covers turning it on, adding people, and the two reasons a whitelisted player is still refused, both of which look like the whitelist is broken.
Before you start
- Operator rights, or access to the server console
- The exact username of each player, with correct capitalisation
- A maintenance window if you are editing server.properties by hand
1. Turn the whitelist on
white-list in server.properties is the switch that refuses players who are not on the list. It defaults to true in current server software, and enforce-whitelist decides whether players who are online when the list changes are kicked.
On a panel this is usually a toggle in the server settings; on a self-hosted server, stop it, edit the file and start it again, because server.properties is only read at startup.
white-list=true
enforce-whitelist=true2. Add each player by name
/whitelist add takes the player's username exactly as they have it. Names are case-sensitive, and a name with a typo produces a whitelist entry nobody matches, which is the most common reason a player says they were added and still cannot join.
Run /whitelist list afterwards and read the names rather than trusting the count. It is the fastest way to catch a typo.
/whitelist add SomeFriend
/whitelist add OtherFriend
/whitelist list
/whitelist remove SomeoneWhoLeft3. Know the two reasons a whitelisted player is refused
First, the case. SomeFriend and somefriend are different strings to the server, and the player's client sends their real capitalisation. If the whitelist entry does not match it exactly, the join is refused with no hint about which half of the problem it was.
Second, the version. A player on a different Minecraft version is refused before the whitelist is even consulted, with a message that says the client is outdated. Both refusals look like failure from the player's chair, and both are fixed differently, so read the message rather than the symptom.
There is a third, rarer case: a player who changed their username. The client sends the current name, and an entry under the old one no longer matches. Ask for the name from their pause menu and update the entry.
[12:33:10 INFO]: Disconnecting SomeFriend: You are not white-listed on this server!
[12:33:12 INFO]: SomeFriend lost connection: disconnected- "You are not white-listed on this server!": the name is not on the list, or the capitalisation differs.
- "Outdated client": the player needs the server's Minecraft version.
- "Failed to verify username": a launcher session problem on their end, not a whitelist one.
4. Manage the list over time
Removing someone is /whitelist remove TheirName, and it takes effect for the next join. With enforce-whitelist on, players who are online when the list changes are kicked too, which is how you remove a group at once.
The list lives in whitelist.json in the server folder, so it is part of your backup. Restore it and the access list comes back with the world.
[
{
"uuid": "00000000-0000-0000-0000-000000000000",
"name": "SomeFriend"
}
]5. Decide what happens to strangers
A whitelist is a name list, not a password. Anyone who learns your friends' usernames can be added by anyone with operator rights, so treat the operator list as the sensitive one: short, known, and reviewed when people join and leave.
If the server is open to strangers and you want people you do not know to be able to try it, that is a different design: leave the whitelist off, protect spawn, and rely on bans for the people who prove they need one. Most groups find the whitelist the better trade, because moderation then happens before a problem rather than after one.
Good to know
- A refused player sees "You are not white-listed on this server", which names the cause. Point them at this guide rather than at the connection one.
- The whitelist and the ban list are separate: a banned player who is also whitelisted stays banned, because the ban is checked as well.
- On PufferHost the server page has a Users section for who can reach the server. The in-game whitelist is a different list, and both have to agree before someone can join.
- Making a server with friends covers the rest of the day-one setup this belongs to.
Common questions
How do I whitelist someone who is not online?
Type /whitelist add TheirName into the server console. Whitelist entries do not require the player to be connected, and they apply the next time they try to join.
I added a player and they still cannot join. Why?
Two usual causes. The name differs from theirs in capitalisation, or their Minecraft version does not match the server's. The console line for their attempt names which of the two it is.
Do operators need to be whitelisted?
No. Operators are exempt from the whitelist check, so adding them is unnecessary. They are still listed separately in ops.json.
How do I turn the whitelist off?
Set white-list=false in server.properties and restart, or use the toggle in your panel if it has one. Anyone who knows the address can join afterwards, so it is worth a decision rather than a convenience.
Does a whitelist stop griefing?
No. It controls who joins, not what they do. Protection plugins and rules handle conduct, and backups handle the recovery when they fail.
Sources
Official documentation this guide was checked against.
Rather not run this on your own machine? PufferHost gives every player a free Minecraft server with 3 GB of RAM and 10 slots. Create a free server.