Minecraft Whitelist: Setup & More
A Minecraft server is only as private as its whitelist. Without one, anyone with the IP can drop in; with one, only the players you name can join. The mechanism itself has been part of Java Edition since the very early multiplayer builds, but how you actually manage it (through the server panel, with in-game commands, or by editing config files directly) is where most setups go wrong.
Quick Solution:
- In server.properties, set white-list=true (or toggle Whitelist on in the GPORTAL panel).
- Add players in-game with /whitelist add <playername>. The server resolves the name to a UUID automatically.
- Optionally, set enforce-whitelist=true to kick non-whitelisted players the moment the list changes.
Bedrock Edition uses allowlist.json instead of whitelist.json, but the workflow is identical.
What Is A Whitelist in Minecraft?
A Minecraft whitelist is a server-side list of player accounts that are allowed to connect. When the whitelist is active, the server checks every incoming connection against that list: known players come straight in, everyone else is rejected with the message ‘You are not whitelisted on this server.’ It is the simplest, most reliable way to keep a private multiplayer server private: no plugins, no permissions juggling, no proxy in front.
The whitelist itself is stored in a file called whitelist.json on Java Edition (or allowlist.json on Bedrock), sitting alongside server.properties in the server’s root directory. Each entry pairs a player name with a UUID (the unique, never-changing ID Mojang assigns to every account) so a player can rename themselves without falling off the list. Players with OP rights are exempt from the Minecraft whitelist check by default, which is worth knowing before you lock yourself out of your own server.
How to Set Up A Whitelist on A Minecraft Server
There are three ways to manage a whitelist, and they all write to the same whitelist.json file under the hood. The right one to use depends on whether you are hosting through a panel like GPORTAL, sitting in-game as an operator, or editing files on a self-hosted box. Below, each path covers the full setup – enabling the whitelist, adding players, and reloading.
GPORTAL Web Interface (Recommended)
On a hosted GPORTAL Minecraft server, the entire whitelist is managed from a single page. No SSH, no file editor and no commands are required:
- Log in at g-portal.com and open My Server.
- Select the relevant server, then click Basic Settings.
- Activate the Whitelist option.
- Enter each player’s name (one per line) under the Whitelist field.
- Save changes and restart the server
Note:Players with OP rights are automatically treated as whitelisted, so admins do not need to be added separately. They will, however, still appear in the panel’s whitelist field once the OP list is read.
Minecraft Whitelist Commands
If you are already in-game as an operator, the Minecraft whitelist commands are the fastest way to enable the list and add players without touching any files. All commands work in single-player ‘Open to LAN’ sessions with cheats enabled, in the multiplayer chat as an OP, and in the server console:
/whitelist on → enable whitelist
/whitelist off → disable whitelist
/whitelist add <name> → add a player
/whitelist remove <name> → remove a player
/whitelist list → show all whitelisted players
/whitelist reload → re-read whitelist.json from disk
The /whitelist add command is the part most older guides get wrong: since Java Edition 1.7.10, the server resolves the player’s name to a UUID automatically through Mojang’s API the moment you add them. You do not need to look up UUIDs by hand or paste them into JSON: the server handles all of it. The only time /whitelist reload is needed is when you have manually edited whitelist.json outside the game and want the running server to pick up the changes without a restart.
Manual Configuration Via server.properties & whitelist.json
For self-hosted setups or any situation where the panel and the console are both unavailable, the whitelist can also be configured by editing two files directly. Stop the server before making changes, then:
- Open server.properties and change white-list=false to white-list=true.
- Open (or create) whitelist.json in the same directory and add each player as a JSON object containing their UUID and name:
[
{
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
"name": "Notch"
},
{
"uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
"name": "jeb_"
}
]
UUIDs can be looked up through Mojang’s public API at:
https://api.mojang.com/users/profiles/minecraft/ <username>
Replace <username> with the player’s current Minecraft name and the response will contain their UUID. Once both files are saved, start the server. Going forward, you can stay in this manual workflow or switch to the in-game commands. The formats are fully compatible.
Enforce Whitelist on Your Minecraft Server
Enabling the Minecraft whitelist only affects new connections. Anyone already on the server when you turn it on, or anyone who was on the list and then got removed, stays connected until they disconnect on their own. The enforce-whitelist setting in server.properties changes that behaviour: with it enabled, the server immediately kicks every player who is no longer on the whitelist the moment the list is reloaded.
enforce-whitelist=true
This setting was added in Java Edition 1.17 and is off by default. You will mostly want it enabled on production servers where the whitelist is your only access control. Otherwise removing a problem player has no effect until they happen to log out. On a GPORTAL server, the same option is exposed in Basic Settings as a separate checkbox. You do not need to edit server.properties by hand. After flipping the setting, run /whitelist reload in the console (or restart the server) for it to take effect.
‘You Are Not Whitelisted on This Server’ – What It Means
If a player tries to join a whitelisted server without being on the list, the connection is closed instantly and the client shows ‘You are not whitelisted on this server’ in red. The error is not a bug, a version mismatch or a network issue: it is the whitelist doing exactly what it was set up to do. There are three things to check, in order, when this comes up:
- the exact spelling of the player name in whitelist.json or the panel field: case usually does not matter, but typos do
- whether the player recently changed their Minecraft username: if you added them by name before 1.7.10-style UUID resolution kicked in, the old name is stuck on the list
- whether the server is actually using the Minecraft whitelist you edited: on a multi-instance setup, it is easy to update the wrong server’s file
If you are the server admin and you locked yourself out, OP rights override the whitelist check, so connecting via the console or RCON to grant yourself OP first is the fastest fix. For broader join issues that look like a whitelist problem but are not (connection refused, timeouts, version mismatches) the dedicated troubleshooting article covers the network side.
FAQ
Set white-list=true in server.properties and restart the server, or toggle the Whitelist option in your hosting panel. On a GPORTAL server, this is a single checkbox in Basic Settings. Once enabled, add players with /whitelist add <name>.
The command is /whitelist add <playername>, run from the server console or by an OP in chat. The server automatically looks up the player’s UUID, so you only need the current Minecraft name. To remove someone, use /whitelist remove <playername>.
The whitelist controls who can connect; enforce-whitelist controls what happens to players who are already connected when the list changes. With enforce off (default), removed players stay until they log out. With it on, they are kicked the moment the list is reloaded.
Yes, Bedrock uses a file called allowlist.json instead of whitelist.json, but the concept is identical and the in-game commands are the same. On a GPORTAL Bedrock server, the panel exposes the equivalent toggle in the same place.
If you are the player: ask the server owner to run /whitelist add <your-current-name>. If you are the owner and locked out: connect via the server console or panel. OP rights override the whitelist by default, so granting yourself OP before connecting solves it.
Whitelist Done: Now, Let the Right People In
A whitelist is one of those settings that takes thirty seconds to flip on and quietly does its job for the rest of the server’s lifetime. Combine it with OP rights for trusted admins and enforce-whitelist=true for quick removals, and you have a clean, dependable access model without a single plugin in the way. For the bigger picture, e.g. backups, performance tuning, version management, our server guide covers what comes after the lock is on the door. Still, the easiest solution is a GPORTAL-hosted Minecraft server for you and your friends. Nothing will stop you there!
