How to Whitelist a Minecraft Server: Keep Your World Private

Why You Should Use a Whitelist

Running a Minecraft server without a whitelist means anyone who knows your server address can join. For a private server shared with a small group of friends, that is usually not what you want. Griefers, bots scanning for open servers, and random strangers can all connect and wreak havoc on a world you have spent hours building.

A whitelist solves this by creating an approved list of players. Only accounts on the list are allowed past the login screen. Everyone else receives a "You are not whitelisted on this server" message and is immediately disconnected. It is one of the simplest and most effective ways to control who has access to your world.

Enabling the Whitelist in server.properties

The whitelist is controlled through two settings in your server.properties file. Open the file from your panel's file manager or via SFTP and locate these two lines:

white-list=false
enforce-whitelist=false

Change both to true:

white-list=true
enforce-whitelist=true

The white-list setting enables the feature. The enforce-whitelist setting tells the server to kick any currently online players who are not on the whitelist whenever you reload it. This is important if you add the whitelist while players are already connected. Save the file and restart your server for the change to take effect.

Adding Players with /whitelist add

Once the whitelist is active, you add players using a console command. You can run this from the server console in your panel or in-game as an operator. The syntax is:

/whitelist add PlayerName

Replace PlayerName with the exact Minecraft username of the player you want to allow. Usernames are case-insensitive for this command, but it is good practice to use the correct capitalisation. The server will confirm with a message like "Added PlayerName to the whitelist." The player can now join immediately without a restart.

If you need to add several players at once, run the command once per username. Each entry is added to whitelist.json in your server directory, which stores the player's UUID alongside their username. Using UUIDs internally means the whitelist still works correctly if a player changes their Minecraft username later.

Removing Players with /whitelist remove

To remove a player from the whitelist, use the counterpart command:

/whitelist remove PlayerName

If enforce-whitelist is set to true, the player will be kicked the next time the whitelist is reloaded or the server restarts. To kick them immediately after removing them, run /whitelist reload from the console. This forces the server to re-read whitelist.json and boot anyone no longer on the list.

Viewing the Current Whitelist

To see who is currently approved, run:

/whitelist list

The server will print all whitelisted players to the console. You can also open whitelist.json directly from your file manager if you prefer to view or edit it as a plain text file. Each entry in the JSON file contains a name and a uuid field. You can add or remove entries by editing this file directly, but always run /whitelist reload afterwards so the server picks up your changes without needing a full restart.

Online Mode and Offline Mode: What Changes?

Most servers run with online-mode=true in server.properties, which means the server verifies each player's account against Mojang's authentication servers. In this mode the whitelist checks the player's UUID, so it works reliably even across username changes.

If your server runs with online-mode=false (also called cracked mode), Minecraft cannot verify player identities against Mojang. In this case the whitelist matches on username only, and anyone can claim any username at the login screen. A whitelist on an offline-mode server still blocks unknown names from connecting, but it provides weaker protection because usernames are not verified. If security matters, keep online mode enabled.

Some BungeeCord or Velocity proxy setups disable online mode on backend servers while enforcing it at the proxy layer. In those configurations, add players to the whitelist on both the proxy and each backend server, or use a plugin designed for proxy-wide access control.