How to whitelist a Minecraft server: every whitelist command

The Minecraft whitelist command lets only the players you name join your server. In the server console, type whitelist add and a player’s name for each friend, then whitelist on. Nothing needs a restart. Everything below is for Minecraft Java 26.3, the current release as of October 2026, with Bedrock covered near the end.

Every Minecraft whitelist command

Type these in the console without a slash. In the game, put a / in front. A player needs operator level 3 or higher to use them. The server commands guide shows how to make yourself an operator.

<targets> is the player’s name. On a server in online mode, which is the default, it must be the name of a real Minecraft account. The syntax is listed on the Minecraft Wiki’s whitelist page.

Turn the whitelist on, step by step

You need access to the server console. On a hosted server it is in your host’s control panel. On a home PC it is the window the server runs in.

1. Add yourself first:

   whitelist add Alex

   The server answers Added Alex to the whitelist.

2. Repeat the command for each friend, with their exact name.

3. Turn the list on:

   whitelist on

   The server answers Whitelist is now turned on. If you see Whitelist is already turned on, it was on already, which is normal on 26.3.

4. Check your work:

   whitelist list

   The answer starts with There are 3 whitelisted player(s): followed by the names.

To test it, ask someone who is not on the list to join the server. They should be refused.

A free Severoo server is online 24/7 as long as you renew it, so people can reach it while you are away. That is a good reason to keep the whitelist on from the first day you make your server.

The two server.properties options

Two lines in server.properties control the whitelist. Our guide to server.properties covers the rest of the file.

white-list=true
enforce-whitelist=false

• white-list turns the whitelist on or off. The default is true since 26.3 and was false before. whitelist on and whitelist off change this line for you.
• enforce-whitelist decides what happens to players who are already online. The default is false.

With enforce-whitelist=false, the list is only checked when someone joins. A player you remove stays in the game until they leave.

With enforce-whitelist=true, the server also kicks online players who are not on the list whenever it reloads the list. In the 26.3 server, that check runs after whitelist on, whitelist remove and whitelist reload, and only while the whitelist is on.

Edit the file while the server is stopped, then start it again. If you upgraded an older server to 26.3, open the file and read the white-list line yourself. We could not confirm whether an upgrade changes an existing file.

What whitelist.json looks like

The list is saved in whitelist.json, in the same folder as server.properties. It is a JSON array with one entry per player:

[
  {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "name": "Alex"
  }
]

The UUID above is a placeholder. A real entry holds the player’s account UUID, which the server fills in when you use whitelist add.

Use the commands instead of editing this file. Paper’s documentation describes it as a data file the server manages, not a config file. If you do edit it, for example to paste a list from another server, run whitelist reload afterward.

Operators and the whitelist

On a Java server, operators can always connect while the whitelist is on, even if they are not on the list. So you cannot lock yourself out as long as you are an operator.

There is one catch. In the vanilla 26.3 server, the enforce-whitelist check looks only at the list. An operator who is online but not listed gets kicked with everyone else, and can rejoin right away. Add yourself to the list to avoid it.

What a blocked player sees

A player who is not on the list is disconnected as they join. The message depends on the server software:

On Paper you can change the text under messages then whitelist in spigot.yml. If a friend gets a different error, such as a timeout, the whitelist is not the cause: see can’t connect to a Minecraft server.

Whitelist a Bedrock server

Bedrock Dedicated Server calls it an allowlist. The idea is the same, but the names differ.

• The setting in server.properties is allow-list. Set it to true.
• Add a player with allowlist add and their Xbox gamertag. Put a gamertag that contains a space in double quotes.
• Remove a player with allowlist remove.
• The list is saved in allowlist.json. After editing it by hand, run allowlist reload.
• The Minecraft Wiki lists on and off as not implemented on Bedrock, so use the allow-list setting.

allowlist add "Gamer Tag"

Each entry in allowlist.json has a name, an optional xuid and ignoresPlayerLimit. Microsoft documents the setting, the commands and the file in the Bedrock Dedicated Server guide. Unlike Java, operators must be on the allowlist too, according to the Minecraft Wiki.

Bedrock players on a Java server with Floodgate

If Bedrock players join your Java server through Geyser and Floodgate, use Floodgate’s own command for them:

fwhitelist add Tim203
fwhitelist remove Tim203

Type the gamertag without the prefix that Floodgate puts in front of Bedrock names, a . by default. The command also accepts the player’s Floodgate UUID. Its permission node is floodgate.command.fwhitelist. Details are in the Floodgate documentation, and our crossplay guide covers the setup.

Common whitelist mistakes

• Sending the address before adding anyone. On 26.3 the whitelist is on from the start, so every friend is refused until you add them.
• Adding names but never turning it on. On versions before 26.3 the list does nothing until you run whitelist on.
• A misspelled name. If the server answers That player does not exist, ask the player to send their name exactly as the game shows it.
• Expecting whitelist remove to kick someone. With enforce-whitelist=false they stay until they leave. Run kick and their name as well.
• Editing whitelist.json and skipping whitelist reload. The server keeps using the list it loaded earlier.
• Using whitelist add for a Floodgate player. Use fwhitelist add.
• Treating the whitelist as a ban. whitelist off lets everyone back in. To keep one person out for good, use ban.