Set Up a Minecraft Server Whitelist – Allow Friends Only

With a Minecraft whitelist, you limit your server to explicitly allowed players. This is useful for private survival worlds, building projects, events, or communities where you want to keep control over access. Three points are crucial: white-list=true, properly maintained player names, and enforce-whitelist=true so changes take effect reliably.

Requirements

You need access to the server console, OP rights in-game, or access to the server.properties file. You should also know the exact Minecraft names of the players. For Java accounts, the player name is usually enough. If Bedrock players join through Geyser, the name may appear with a prefix depending on the Geyser configuration; the initial example uses a dot.

If you are currently setting up the server from scratch, the advanced guide Rent and Set Up a Minecraft Server – Complete Guide 2026 will help you. For more co-op setups with a similar access concept, you can also find the Rent and Set Up a Valheim Server – Co-op Guide 2026.

Set Up a Minecraft Whitelist

What is the whitelist?

The whitelist is access control for your server. Only players on the list can join. It does not replace moderation, but it prevents unknown accounts from simply joining via the server address. For paid multi-game hosting, this is especially practical because you can separate server access, support cases, and operational workflows more clearly: anyone who is not on the list cannot get in.

Microsoft documents the corresponding Bedrock command as /allowlist; /whitelist is listed there as an alias, and the actions add, remove, list, off, on, and reload are described: Microsoft Learn on allowlist/whitelist. For Java servers, the server.properties entries and /whitelist commands shown below remain the practical foundation.

Enable the whitelist

In server.properties:

white-list=true
enforce-whitelist=true

While you are already in server.properties: the motd line determines your server list entry — you can style it with colors using our free MOTD Generator.

Or with an in-game command:

/whitelist on

If you edit the file directly, stop the server first or restart it afterward. Changes made through commands are more convenient during live operation because you do not have to switch into the file every time.

Add players

/whitelist add <Spielername>

For Bedrock players (through Geyser):

/whitelist add .<BedRockName>

Pay attention to spelling. If a player cannot join even though you have added them, compare the name with the display in the login attempt or in the server logs. With Geyser setups, it is especially important whether a prefix is used and how uppercase/lowercase is handled.

Manage the whitelist

Use /whitelist list after every larger change. This lets you spot typos or accidentally duplicated names immediately. If you remove a player, enforce-whitelist=true is important so the exclusion does not only become relevant on the next connection attempt.

whitelist.json

The whitelist is saved in whitelist.json:

[
  {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name": "PlayerName"
  }
]

Only edit this file if you know what you are doing. For normal operation, commands are safer because the server manages names and UUIDs appropriately. If you change the file manually, use /whitelist reload afterward or restart the server.

Check the result

First use /whitelist list to check whether all desired players are included. After that, a listed player should be able to join. An unlisted account should be rejected. Also check the server console: there you can see whether the join attempt fails because of the whitelist, an incorrect name, or another issue.

For private projects, a short routine makes sense: add player, test join, show list, document change. Especially with multiple admins, this prevents support questions from staying unclear later.

Troubleshooting

Player is on the list but cannot join

Check the exact name, the game mode, and possible prefixes with Geyser. If in doubt, remove the entry with /whitelist remove <name> and then add it again.

Removed players stay online

Set enforce-whitelist=true and reload the list with /whitelist reload. Without this setting, removed players may remain connected until they disconnect, depending on the server state.

Changes in the file do not take effect

If you changed server.properties or whitelist.json manually, reload the whitelist or restart the server in a controlled way. Also check whether you really edited the file of the active server instance.

Confusing OPs and whitelist

Operator rights are administrative rights, not a clean access list. Keep OPs limited and maintain the whitelist separately. This keeps it clear who is allowed to administer and who is only allowed to play.

Tips

• Enforce Whitelist: Enable enforce-whitelist=true so players are kicked when they are removed from the list
• OPs: Operators (OPs) can also join without being on the whitelist if enforce-whitelist is off
• Automation: Use plugins like EasyWhitelist for web-based management

Testing, Limits, and a Safe Way Back

The guide “Set Up a Minecraft Server Whitelist – Allow Friends Only” applies to the server type described in the article and the version status visible at the time of testing. Menu names, available versions, mod or plugin compatibility, and required resources may differ after updates. So do not apply values to another game, loader, or server version without checking them first.

Create a backup of the affected files before making changes to the world, savegame, configuration, or extensions. Then change only one related step at a time and test it with the same client and server version you want to play with later.

A successful individual test is not a guarantee of performance or availability. World size, mods, plugins, player count, network path, and simultaneous load can change the result. Document the version, change, and test result so you can understand later deviations.

FAQ

Do I need to restart after every change?

Not necessarily. If you use commands like /whitelist add, /whitelist remove, or /whitelist reload, you can manage the list during live operation. After manual file changes, a reload or restart is sensible.

Is the whitelist better than a password?

For Minecraft, the whitelist is the more common approach because it allows specific accounts. A password does not protect against shared access data, while a whitelist is tied to player names or accounts.

Should I always enable enforce-whitelist=true?

For private servers, this usually makes sense. The setting ensures that removed players do not stay online after a reload even though they are no longer on the list.

Does the whitelist work with mods and plugins?

Yes, the basic whitelist is a server function. Plugins can provide additional management, but they should be chosen carefully and kept up to date.

What do I do with Bedrock players through Geyser?

Check how your Geyser setup maps Bedrock names. The example uses .<BedRockName>. If joining fails, check the name actually shown in the console or logs.