How to Whitelist Players on a Minecraft Server

A whitelist (allowlist) restricts your server to a list of approved players — essential for a private SMP or any world you don't want strangers joining. This guide covers enabling and managing it on both Java and Bedrock.

Enable the whitelist (Java)

The simplest way is from the server console or in-game as an operator. Turn it on:

/whitelist on

That instantly kicks anyone not on the list and blocks new non-whitelisted joins. You can also set it in server.properties:

white-list=true
enforce-whitelist=true

enforce-whitelist=true kicks already-connected players who aren't on the list when you reload — useful for locking down mid-session.

Add and remove players

Use the whitelist commands with the player's exact username:

/whitelist add Steve
/whitelist remove Alex
/whitelist list
/whitelist reload

Adding a player fetches their UUID from Mojang, so the server must be in online mode (the default). The data is stored in whitelist.json:

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

You can edit that file directly, but use /whitelist reload afterward so the server picks up changes.

Operators bypass the whitelist

Server operators (ops) can always join, whitelist or not. That's handy for admins — see how to op yourself and manage admins. Keep your op list tight for the same reason you keep the whitelist tight.

Bedrock uses an allowlist

On a Bedrock Dedicated Server, the equivalent is allowlist.json (older versions call it whitelist.json) plus allow-list=true in server.properties. Add players by gamertag:

allowlist add PlayerGamertag
allowlist reload

For crossplay setups with Geyser and Floodgate, remember Bedrock players may join with a username prefix — whitelist that exact name.

When to use it

A whitelist is the backbone of a private SMP for friends. It's also a first-line security measure for any server — combined with regular backups, it keeps griefers and unwanted guests out entirely.

Bans work alongside the whitelist

A whitelist keeps unknown players out; bans remove known troublemakers who were let in. The two work together. From the console or as an op:

/ban Griefer  Reason for the ban
/ban-ip 203.0.113.55
/pardon Griefer
/banlist

Banned players are recorded in banned-players.json and banned-ips.json. For a public server, an IP ban is stronger than a name ban since it stops the player rejoining under a new username — though determined players can change IPs, which is why a whitelist is the more reliable lock for a private world.

Common whitelist problems

A few issues come up repeatedly:

• "You are not whitelisted" for a valid player: you added a typo'd or old username. Usernames can change — re-add the current one and run /whitelist reload.
• Nobody can join after enabling it: that's expected — you must add each player. Add yourself too, or rely on op (ops bypass it).
• Whitelist ignored: check white-list=true is set in server.properties and that you reloaded.

Whitelisting on a network or crossplay server

If you run a proxy network, enable the whitelist on the backend servers (or use a proxy-level plugin), not just the proxy. On a Geyser crossplay server, Bedrock players joining via Floodgate use a prefixed name (e.g. .Steve) — whitelist that exact prefixed name, or they'll be rejected. Pair the whitelist with regular backups and a tight op list for a genuinely secure private SMP.

Whitelist plus a good MOTD

A whitelisted server rejects unlisted players with a generic message, which can confuse a friend who's waiting to be added. Two small touches help. First, set a clear server-icon.png and a welcoming motd in server.properties so your friends recognise the right server in their list. Second, agree an "add me" channel — a Discord or group chat where someone requests access and an op runs /whitelist add. On a plugin server you can go further: plugins can show a custom "you're not whitelisted, apply at..." message, or even run an application/approval flow. For a small SMP, the manual approach is perfectly fine and keeps control tight. Combined with a short op list and regular backups, a whitelist is the backbone of a private, drama-free server.

FAQ

How do I whitelist someone on my Minecraft server?

Run /whitelist add <username> in the console or as an op, after enabling it with /whitelist on.

Where is the whitelist stored?

In whitelist.json in the server root. It holds each player's UUID and name. Edit it, then run /whitelist reload.

Do ops need to be whitelisted?

No — operators bypass the whitelist and can always connect. That's why op access should be limited.

Does the whitelist work in offline mode?

It's designed for online mode, where usernames map to Mojang UUIDs. In offline mode it matches by name only, which is far less secure.

A whitelist keeps the right people in and everyone else out. Run your private world on Nxeon's Minecraft server hosting with full root access to manage it your way.