Put a whitelist on your Minecraft server

The whitelist only lets in the players you've chosen. It's the simplest protection against strangers, and the basis of semi-private servers, where you get in by application. It's also useful during maintenance or before opening, to test with the team.

Turn on the whitelist

From the console (or in game, with operator rights):

whitelist on
whitelist add Steve
whitelist list

The whitelist on command sets white-list=true in server.properties: the setting survives a restart. Added players are saved in whitelist.json, with their username and UUID.

Command	Effect
whitelist on / off	turns the list on or off
whitelist add <username>	adds a player
whitelist remove <username>	removes a player
whitelist list	shows the list
whitelist reload	rereads whitelist.json after a manual edit

enforce-whitelist: kick those no longer on the list

By default, removing a player from the list doesn't kick them if they're online: they just won't be able to come back. With enforce-whitelist=true in server.properties, the server immediately kicks any online player who isn't on the list when it's reloaded. It's the setting to turn on for maintenance: whitelist on, and everyone except the team is out.

The UUID trap

The whitelist remembers the player's UUID, not just their username: a player who changes username stays allowed. Two cases need attention:

• Server in online-mode=false (unofficial accounts): the UUID is computed from the username. Anyone taking an allowed player's username gets past the whitelist. On such a server, the whitelist only protects with a password authentication plugin. See Protect your server.
• Behind a proxy (Velocity): turn on player info forwarding (modern forwarding), otherwise the UUIDs received by the servers don't match the players'. The Username ↔ UUID tool gives a username's official UUID and offline UUID, to check.

Bedrock players

With Geyser and Floodgate, Bedrock players don't have a Java account: whitelist add can't find them. Floodgate provides its own command:

fwhitelist add Steve

Give the player's Xbox username (their gamertag), as it appears in Minecraft Bedrock.

An application-based whitelist

Many semi-private servers work like this: you apply, the team approves, you're added. To make it last:

• A short form: exact username, age, how the player heard about the server, one or two questions about what they're looking for.
• An answer within 48 hours. Beyond that, the player has gone elsewhere.
• Written criteria, so every team member decides the same way.
• A welcome message on first visit: rules, Discord channel, first steps.

The whitelist becomes a selling point: on your listing, state "whitelist by application" and the response time. Players looking for a calm community seek exactly that.

A whitelist linked to Discord

DiscordSRV can require a player to have linked their Discord account to connect: only members of your Discord server get in, without adding anything by hand. It's handy for a community already gathered on Discord; the guide Set up your server's Discord details the linking.

Common mistakes

• A typo in the username: the player is refused. Check with whitelist list.
• Editing whitelist.json without whitelist reload: the change isn't taken into account.
• Forgetting white-list=true after changing host: the server is open to all. The server.properties generator shows this setting and the others.
• Confusing whitelist and operator list: being on the whitelist gives no rights, only access.