How to whitelist a Minecraft server
Use whitelist commands and server.properties settings to keep a Java server private while you add trusted players.
A whitelist limits who can join a Minecraft Java server. It is useful for private SMPs, family servers, staff testing worlds, creator events, and small community launches.
The short version is simple: turn the whitelist on, add player names, reload the whitelist, then confirm the matching server.properties lines. Do this from the server console or with an operator account in game.
quick whitelist commands
Console commands/whitelist on
/whitelist add PlayerName
/whitelist reload
/whitelist listReplace PlayerName with the exact Minecraft username. Usernames are case-insensitive for most command use, but copying the visible account name reduces mistakes when you manage a longer player list.
server.properties settings
Most Java servers also store whitelist behavior in server.properties. For a private server, these two lines are the main settings to check.
server.propertieswhite-list=true
enforce-whitelist=true| Setting | Use |
|---|---|
| white-list=true | Turns the whitelist on for new join attempts. |
| enforce-whitelist=true | Keeps whitelist rules strict when players reconnect or when the list changes. |
| white-list=false | Opens the server to anyone who can reach the address. |
step-by-step setup
- Stop public sharing of the server address until the whitelist is ready.
- Run /whitelist on from the console or as an operator.
- Add each player with /whitelist add PlayerName.
- Run /whitelist reload after batch edits or file changes.
- Run /whitelist list to check who can join.
- Ask one allowed player and one unlisted test account to try joining if you can.
Do not edit whitelist.json by hand unless the server is stopped and you know the UUID format. For normal server management, console commands are safer.
common whitelist problems
- The player name has a typo. Copy it from the account owner or from a previous join log.
- The whitelist was edited but not reloaded. Run /whitelist reload.
- The command was run in chat without operator permission. Use the server console.
- A proxy or network layer has its own access rules. Check the proxy config as well.
- The server is Bedrock or a custom network. Some Bedrock and proxy setups use different commands.
before you open the server
A whitelist is only one part of a clean launch. Check online-mode, backups, operator permissions, spawn protection, and the MOTD before you share the address. If the server will later become public, add it to ServerBuddy after it responds online and has the right mode, version, and player limit.