How to Whitelist a Minecraft Server (Java & Bedrock, 2026)

A whitelist is a list of approved players who are allowed to join your server. Anyone not on the list gets kicked with the message "You are not whitelisted on this server." It's the easiest way to keep a private server for friends only.

Method 1: Enable Whitelist via server.properties (Recommended)

This is the most reliable method — it works on Paper, Spigot, Vanilla, and Fabric servers.

Step 1: Open server.properties

Find the file in your server root directory (same folder as the .jar file). Open it with any text editor.

Step 2: Change these two lines

# server.properties
white-list=true
enforce-whitelist=true

Setting white-list=true enables the list. Setting enforce-whitelist=true ensures that if you add/remove whitelist entries while the server is running, online players who are no longer on the list get kicked immediately.

Step 3: Restart the server

Changes to server.properties only take effect after a full restart. After restarting, the /whitelist commands become active.

Method 2: Enable Whitelist via Console Command

If the server is already running, you can enable the whitelist without a restart:

whitelist on

Type this directly in the server console (no leading slash needed in console). This also automatically sets white-list=true in server.properties.

Whitelist Commands — Full Reference

Command	Description	Permission
/whitelist on	Enable the whitelist	OP or Console
/whitelist off	Disable the whitelist (everyone can join)	OP or Console
/whitelist add Steve	Add player "Steve" to whitelist	OP or Console
/whitelist remove Steve	Remove "Steve" from whitelist	OP or Console
/whitelist list	Show all whitelisted players	OP or Console
/whitelist reload	Reload whitelist.json from disk (after manual edits)	OP or Console

Method 3: Edit whitelist.json Directly

For bulk additions, you can edit whitelist.json directly in your server root. It looks like this:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  },
  {
    "uuid": "8667ba71-b85a-4004-af54-457a9734eed7",
    "name": "jeb_"
  }
]

You can get a player's UUID from mcuuid.net by entering their username. After editing, run /whitelist reload in console (no restart needed).

Adding Players Without Whitelist Permission

If you want moderators to be able to add players to the whitelist without giving them full OP, use a permission plugin like LuckPerms:

# Give permission via LuckPerms:
/lp user ModName permission set minecraft.command.whitelist.add true
/lp user ModName permission set minecraft.command.whitelist.remove true
/lp user ModName permission set minecraft.command.whitelist.list true

Bedrock Edition Whitelist

Bedrock servers (Bedrock Dedicated Server / GeyserMC) use a slightly different system. The file is called allowlist.json (renamed from whitelist.json in newer BDS versions):

# allowlist.json — Bedrock Dedicated Server
[
  {
    "ignoresPlayerLimit": false,
    "name": "PlayerName",
    "xuid": "2535416071868450"
  }
]

Bedrock commands:

allowlist add PlayerName
allowlist remove PlayerName
allowlist list
allowlist reload

XUIDs (Xbox User IDs) can be found in the BDS console output when a player tries to connect for the first time.

Whitelist vs IP Bans — What's the Difference?

Common Whitelist Issues and Fixes

"You are not whitelisted" even after being added

This usually means the username was typed incorrect, or the player is using a different account than expected. Verify with /whitelist list and check spelling (Minecraft usernames are case-sensitive in some implementations).

Whitelist works but OP players can bypass it

By default, OP players can join even if the whitelist is enabled. To change this behavior in Paper, set:

# paper.yml (or paper-global.yml in newer Paper)
settings:
  whitelist-override-for-ops: false

Whitelist disabled itself after restart

You may have enabled via /whitelist on but server.properties still has white-list=false. The console command updates the running server but may not persist the change properly in some older versions. Always confirm white-list=true is in server.properties.