How to Whitelist a Minecraft Server the Right Way

A whitelist is the cleanest way to control exactly who gets onto your server, and it's built right into vanilla — no plugin, no host panel feature, nothing to install. The trouble is that most owners set it up halfway. They flip it on, then a Bedrock player can't get in, or an admin they trust is locked out while their own account walks right through. None of that is a bug — it's just the parts of the setup that aren't obvious until they bite you.

This is the owner side of the whitelist: the commands, the settings that make names actually accurate, the Geyser wrinkle for crossplay servers, and the one real trade-off you have to weigh between a closed door and being found. If you landed here because you got bounced with a "not whitelisted" message as a player, the companion piece on what whitelisted means and how to get added is the one you want — this post stays on the operator.

The whitelist commands, start to finish

The core set is small and you'll use most of it from the console or in-game. /whitelist on and /whitelist off toggle enforcement. /whitelist add <name> and /whitelist remove <name> manage entries, and the player does not need to be online to be added or removed — you can approve someone before they ever show up. /whitelist list prints everyone who's approved, and /whitelist reload re-reads whitelist.json from disk.

There are two ways to turn it on. You can run /whitelist on live, or set white-list=true in server.properties before the server boots. Both enforce the same thing; the command just saves you a restart.

The gotcha that catches people: turning the whitelist on does not kick anyone who's already connected. Existing sessions ride along until they disconnect on their own, and they only get refused on the next reconnect. If you want a removal to take effect right now instead of next time, set enforce-whitelist=true in server.properties. With that on, a /whitelist reload immediately removes anyone who's no longer on the list. That combination — enforce-whitelist plus a reload — is the thing that makes "get them off now" actually mean now.

One more that owners forget about themselves: on a Java server, operators bypass the whitelist by default. An op can always connect even if their profile was never added. That sounds convenient, and it is, right up until you try to hand access to a co-admin who isn't an op and discover they can't get in because you never added anyone to the list — you'd just been coasting on op bypass the whole time.

So the practical workflow is: add yourself and your trusted staff first, flip it on, confirm everyone landed with /whitelist list, and keep doing adds from the console or in-game as people ask. On a normal setup you never need to open whitelist.json and edit it by hand.

Make names accurate: keep online-mode on

This is the setting that decides whether your whitelist guards a person or just a string of text, so it's worth understanding rather than copying.

On an online-mode server (online-mode=true), each approved player is stored by their account's UUID, and Mojang/Microsoft authentication verifies that whoever connects really owns that name. When you run /whitelist add SteveBuilder, the server resolves the username to the right account and writes the UUID for you. The name is just what you typed — the account behind it is what got verified.

Switch to online-mode=false and that all comes apart. The server can't authenticate accounts, so it generates UUIDs locally from the username text itself. Anyone can connect under any name they type. Your whitelist is now guarding a name string, not a person, and it's trivial to walk past — someone just types an approved name and they're in. For any server you list publicly or expect strangers to find, keep online-mode=true. It's the setting that gives your whitelist, your bans, and your ops any meaning at all. Offline mode belongs only on a genuinely private, LAN-style box, and even there a whitelist by itself is not a security boundary.

There's a nice side effect of doing it right, too. Because online mode binds approval to the account and not the spelling, a whitelisted player who later changes their username keeps their access automatically — you don't have to re-add them. That convenience only exists when online mode is on.

Whitelisting Bedrock and Geyser players

If you're running crossplay through Geyser and Floodgate so Bedrock players can join your Java server, the plain whitelist command needs a small adjustment. Those players don't have Java accounts, so /whitelist add <name> can fail outright or store the wrong entry — the classic one is the "could not request xuid" error.

Floodgate ships its own command for exactly this: /fwhitelist add <bedrock_username>. That adds the Bedrock player to whitelist.json the correct way. The catch is that you do not include the prefix when you use it.

The prefix is the next thing to know about. Floodgate gives every Bedrock player a . in front of their name by default — so a Bedrock player shows up as .SteveBuilder — specifically to avoid collisions with an identically-named Java player. When you reference that player in most other commands you include the dot; with fwhitelist you leave it off and pass the bare username.

Bedrock gamertags bring one more naming quirk: Floodgate replaces spaces with underscores. A player whose gamertag is "Steve Builder" is referenced as Steve_Builder in commands, so keep that in mind when an add doesn't seem to match.

A word of caution before you tidy any of this up: leave the . prefix in place unless you are genuinely certain no name will ever collide across editions. The prefix is configurable, and owners sometimes strip it for looks — but removing it is exactly how you create the impersonation problem it was put there to prevent. This is a setup note, not a full Geyser tutorial; if you're running crossplay you've already got the rest of that pipeline in place.

The trade-off: a closed whitelist vs. being discoverable

A whitelist is a closed front door, and that cuts both ways. It buys you a vetted community and a lot less moderation work, because nobody plays until you've approved them. But that same gate slows growth, because every new player has to be let in by hand — which is rough if you're trying to build a population from zero.

What it does not do is hide your server, and this is the part people get wrong. A whitelist works at the login step only. Your server still answers status pings and still shows up as online on a server list, with its name, version, and current player count intact. People can find it, ping it, and see it's alive; they just can't join until you add them.

Because the listing keeps working, you don't actually have to choose. You can list the server so it stays discoverable and keeps gathering votes and visibility, keep the whitelist on, and publish a clear, low-friction way in — a Discord link, a short application — right there in the listing, so an interested player knows exactly how to get added. The server stays visible and the way in is right there in the listing — players just can't walk in until you add them.

If you're a new server deciding on a posture, think about opening up during launch to build a base and a bit of reputation first, then closing the whitelist once you've got the community you actually want. Starting fully closed and waiting for applications usually means waiting a long time. And since the directory rewards communities that are active and well-run, a whitelisted server that posts its join steps and keeps showing up can still climb — that's covered in how the rankings work. Whitelisted SMP-style communities tend to live in categories like the survival listings, which is a good place to see how others present the way in.

FAQ

Should I ever edit whitelist.json by hand?

On a normal online-mode server you don't need to. The /whitelist add command resolves the username to the correct account and writes the entry for you, UUID included, so hand-editing only invites typos and mismatched IDs. The one time people reach for the file directly is a bulk import or a recovery, and even then you should run /whitelist reload afterward so the server picks up the changes. For day-to-day approvals, stick to the commands.

What happens to the whitelist if I switch a player's name or migrate the server?

On an online-mode server the entries are keyed by UUID, so a player keeps their access through a name change with no action from you. The risk shows up when you move the world or copy files to a new host: as long as whitelist.json and the same online-mode=true setting come along, the list carries over intact. The thing that breaks it is changing online mode in the process — flip to offline and the locally generated UUIDs won't match the real accounts, so the existing entries stop lining up with the players they were meant for.

Does running a whitelist slow my server down or cost performance?

No. The whitelist is a one-time access check that runs the instant a player connects — it has no effect on tick rate, in-game performance, or how the server handles people who are already online. A bigger list doesn't add meaningful overhead either. Performance comes from your hardware, player count, plugins, and view distance, not from whether the door is gated. Whitelisting is purely access control, not a load on the server.