How to whitelist your server

Before you start

• You will need to open and login to the panel of your Minecraft server.
• Whitelisting only blocks the player who tries, It does not remove players who are already online, and it does not affect server operators, who can always join.
• If your server is in offline mode (online-mode=false in server.properties), read the UUID section below before you add anyone. This is the most common reason whitelist entries fails without letting the user know.
• No restart is needed to toggle the whitelist from Console. A restart is only needed if you set white-list=true directly in server.properties instead.

Steps

Turn the whitelist on (Console)

1. 1Open Console in the panel.
2. 2Run:
   whitelist on
3. 3Check if the server replies Whitelist is now turned on.

Add and remove players (Console)

• Add a player:

whitelist add PlayerName

• Remove a player:

whitelist remove PlayerName

• List everyone currently whitelisted:

whitelist list

• Turn the whitelist back off:

whitelist off

Alternative way: edit whitelist.json directly

1. 1Open Files and locate whitelist.json in your server's root directory.
2. 2Each entry needs both a uuid and a name field:
   [ { "uuid": "069a79f4-44e9-4726-a5be-fca90e38aec5", "name": "PlayerName" }]
   
3. 3Save the file.
4. 4Run whitelist reload in Console. Edits made directly to the file are not picked up until you reload, and a restart alone does not force a reload either.

Turn the whitelist on at boot (server.properties)

1. 1Open Files → server.properties.
2. 2Set:
   white-list=true
3. 3Save and restart the server from Startup.

This is the setting to use if you want the whitelist enforced every time the server boots, without having to run whitelist on manually after a crash or reboot.

Bedrock servers

Bedrock does not use whitelist.json. It uses allowlist.json, and the toggle in server.properties is allow-list=true rather than white-list=true. Player entries in allowlist.json use name and ignoresPlayerLimit, not UUID.

Verify

• Run whitelist list in Console and confirm the player's name appears.
• Have the player join. If they are not on the list, they should see "You are not white-listed on this server!"
• Have an operator or already-online player confirm they can still join normally. Whitelisting does not remove existing sessions or block ops.

If it doesn't work

• Edited whitelist.json but the player still can't join, or still gets in after removal. You edited the file but never ran whitelist reload, or you restarted instead. Run whitelist reload in Console after any direct file edit.
• Added a player by name, but they still can't connect, on an offline-mode server. Offline-mode servers generate UUIDs from the username locally rather than pulling the real Mojang UUID. If the server later switches to online mode, or the player's client resolves a different UUID, the whitelist entry no longer matches. Remove the stale entry and re-add the player while the server is in the mode it will actually run in.
• whitelist.json has a name but a blank or malformed uuid field. Delete the broken entry and re-add the player with whitelist add PlayerName from Console rather than typing the UUID by hand.
• Whitelist is on, but random players are still getting in. Check for a stray whitelist off in a startup script or Schedule, and confirm you did not add the account as an operator in ops.json, since ops bypass the whitelist entirely.

Related

• How to Add and Remove Server Operators
• How to Edit server.properties