Whitelist on Your Minecraft Server: How to Keep Strangers Out

Why use a whitelist?

By default your server is open: anyone who knows the address can join. A whitelist flips that around - only the players you have put on the list are let in. It is the simplest and most effective protection for a private server or a closed community.

Operators (OP) are whitelisted automatically. They do not need to be on the list to join.

---

Step 1 - Turn the whitelist on

The quickest route is the console. Open Console in the Potionhost control panel and type:

whitelist on

You can also make it permanent in server.properties under Files:

white-list=true

Save and restart the server.

In the console the command is written without a slash. In-game you write it with one: /whitelist on.

---

Step 2 - Add and remove players

Command	What it does
whitelist add Name	Adds a player to the list
whitelist remove Name	Removes a player again
whitelist list	Shows everyone on the list
whitelist reload	Reloads the list from the file
whitelist off	Turns the whitelist off again

The server looks up the player UUID with Mojang itself, so all you need is the username - spelled exactly right.

---

Step 3 - Remove the people who are already inside

This one surprises a lot of people: white-list=true only blocks new logins. Players who are already on the server get to stay.

If you want the server to kick everyone who is not whitelisted whenever the list changes, you also need:

enforce-whitelist=true

Save server.properties and restart. Now anyone outside the list is kicked every time the whitelist is reloaded.

---

Editing whitelist.json directly

If you need to add a lot of players at once, you can edit whitelist.json in the server root directory:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  }
]

Run whitelist reload in the console afterwards - otherwise the server will not notice. If you edit the file while the server is running without reloading, your changes are overwritten at the next shutdown.

---

The most important setting of all: online-mode

online-mode=true is the default, and it means Mojang confirms that the player actually owns the account they are logging in with.

If you set online-mode=false, your whitelist is effectively worthless. Anyone can then log in with any username - including the name of someone on your whitelist. Leave it on true.

If you do run an offline-mode server, you need a login plugin such as AuthMe to verify players with a password.

---

Kick, ban and pardon

Command	What it does
kick Name reason	Removes the player now - they can rejoin
ban Name reason	Bans the player permanently
ban-ip 1.2.3.4	Bans an entire IP address
banlist	Shows every ban
pardon Name	Lifts a ban
pardon-ip 1.2.3.4	Lifts an IP ban

Bans are stored in banned-players.json and banned-ips.json in the root folder.

---

More settings that protect your server

Setting	Default	What it does
spawn-protection	16	The area around spawn where only operators may build. 0 disables it
enable-status	true	Set to false and the server appears offline in the server list
hide-online-players	false	Set to true to hide the player list from the outside
prevent-proxy-connections	false	Kicks players whose network does not match Mojang information

prevent-proxy-connections also hits perfectly ordinary players on a VPN or mobile network. Only enable it if you have an actual problem.

If you run Paper or Spigot, two plugins are worth knowing: LuckPerms to control who may do what, and CoreProtect to roll back grief if the damage happens anyway.

---

Troubleshooting

Symptom	Likely cause	Fix
You are not white-listed on this server!	The player is not on the list	Run whitelist add Name
Everyone can still join	white-list is not set to true	Run whitelist on and check server.properties
The whitelist works, but nobody gets kicked	enforce-whitelist is false	Set it to true and restart
Changes to whitelist.json disappeared	The file was edited while the server was running	Stop the server, edit, start again
A whitelisted player is rejected	The player changed their name	Remove and add the player again
Strangers join despite the whitelist	online-mode is set to false	Set it to true and restart
An admin joins without being on the list	They are an operator	That is normal - see the OP guide

---

Good advice

• Use white-list=true and enforce-whitelist=true together. The first one alone is not enough.
• Keeping the server address secret is not protection. Addresses get shared.
• Do not hand out OP to people you do not know - see How to Make Yourself OP (Admin) on Your Minecraft Server.
• Install CoreProtect before you need it. It cannot roll back anything that happened before the plugin was installed.
• Take a backup before opening the server up to a larger group.

Did somebody get in who should not have? Contact our support team - we can help you regain control of access.