How to Whitelist a Minecraft Server (Java and Bedrock)

To whitelist a Minecraft Java server, open the console and run /whitelist add PlayerName for each player, then /whitelist on. Only people on the list can join. Remove someone with /whitelist remove PlayerName. You need operator rights, or you can type the commands in the server console.

This guide covers Minecraft Java Edition 1.21 and newer on Vanilla, Paper, Purpur and Fabric, plus a short section on Bedrock. If you are still setting up your first world, start with how to make a Minecraft server for friends.

What a whitelist does

A whitelist is a list of players who are allowed to join. When it is on, everyone else sees a message and cannot connect, even if they know your server address. It is the simplest way to keep a private server private.

It is a good fit for a server with friends, family, a school club or a small SMP. It will not help a public server, because there you want strangers to be able to join. For those, look at a ban list, a permissions plugin and anti-grief tools instead.

1. Turn the whitelist on

There are two ways. Pick one.

• In the console (or in-game as an operator), type /whitelist on. The server says the whitelist is turned on.
• Or open server.properties, set white-list=true, save the file and restart the server.
• To turn it off again, type /whitelist off or set white-list=false.

Turning it on does not kick anyone who is already online. We cover that in step 5.

2. Add players to the whitelist

• Ask each player for their exact Minecraft Java username.
• Type /whitelist add PlayerName in the console. The server replies that it added the player.
• Repeat for every player. There is no limit on the size of the list.
• Check the result with /whitelist list. It prints every name.

You can use a selector instead of a name when the player is online, for example /whitelist add @a adds everyone currently connected. This is a quick way to whitelist your group before you switch the whitelist on.

3. Remove a player

Type /whitelist remove PlayerName. The player stays connected until they leave, but they cannot come back. If you want them out right away, kick them with /kick PlayerName as well, or use step 5.

All the whitelist commands

These commands need operator permission level 3 or higher. If you are not an operator yet, run them from the server console, which always has full rights. To make yourself an operator, run op YourName in the console.

4. Edit whitelist.json by hand

The list lives in whitelist.json in your server folder. Each entry has a name and a UUID, like this:

• [ { "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5", "name": "Notch" } ]
• Save the file, then run /whitelist reload so the server reads it. No restart is needed.
• Keep the JSON valid: commas between entries, and straight quotes. One missing comma and the server ignores the file.

Editing by hand is useful when you move a server. Copy whitelist.json from your old server to the new one and the whole list comes with you. See how to move your server to Tree Host for the other files worth copying.

5. Kick players who are not on the list

By default, the server only checks the whitelist when someone tries to join. Set enforce-whitelist=true in server.properties and the server also removes anyone who is not on the list when you run /whitelist reload or restart. Use it when you turn the whitelist on for a server that already has visitors.

• Set white-list=true and enforce-whitelist=true in server.properties.
• Add everyone you want to keep with /whitelist add.
• Run /whitelist reload. Players not on the list are kicked.

6. Fix 'You are not white-listed on this server'

This is the message a blocked player sees. Check these causes in order:

• The name is missing. Run /whitelist list and look for it.
• A typo. Remove the wrong entry and add the right name. Ask the player to copy their name from the Minecraft launcher.
• Offline mode. If online-mode=false, the UUID comes from the exact spelling of the name, so Steve and steve are two different players. Match the capital letters. Offline mode is also a security risk, so only use it behind a proxy that checks accounts.
• You edited the file but did not reload. Run /whitelist reload.
• The player changed their Minecraft name. The UUID stays the same, but the stored name is old. Remove the entry and add the new name.

More join problems, such as a wrong port or a version mismatch, are in the troubleshooting guide.

Whitelist on Bedrock

Bedrock uses different words and files. How you do it depends on how your Bedrock players connect.

The Bedrock Dedicated Server stores its list in allowlist.json. With Floodgate, Bedrock names get a prefix (a dot by default) so they do not clash with Java names, so ask Bedrock players to join once or check the prefix in your Floodgate config before you add them. Crossplay needs plugins, and our guide on adding plugins to a Minecraft server shows how to install them.

Whitelist on Tree Host

You do not need to remember any of these commands on Tree Host. Set your Minecraft name in Account, open the Console tab and click Whitelist me. The OP me button whitelists you and gives you operator rights in one click. The whitelist switch also sits in Settings, under game settings. The servers guide shows where each button is.

Tree Host has not launched yet. Anyone who is signed in can try the shared demo server now, and creating your own server opens at launch. See what Tree Host offers in the meantime.

Keep your list tidy

• Whitelist by name only after you have checked the spelling with the player.
• Review the list once a month with /whitelist list and remove people who left.
• Keep a backup copy of whitelist.json next to your world backup.
• If you run Paper, Purpur or Fabric, the commands are the same as Vanilla. See Paper vs Purpur vs Fabric if you are choosing a server type.

More guides

• How to Move Your Minecraft Server to Tree Host
• Paper vs Purpur vs Fabric vs Folia: Which Minecraft Server Should You Run?
• How to Install a Minecraft Modpack on a Server (Step by Step)
• How to Add Plugins to a Minecraft Server (and Which Ones to Start With)