How to Fix You Are Not Whitelisted on This Server in Minecraft

The Error

You are not whitelisted on this server!

This message means the server has whitelist mode enabled and your username or UUID is not on the approved list. The server rejects your connection before you can join the world.

Quick Fix

Ask the server administrator to add you. The admin runs /whitelist add YourUsername from the server console or in-game with operator permissions. You should be able to connect immediately after being added.

Step-by-Step Diagnosis

1. Confirm your exact username. Usernames are case-insensitive but must be spelled correctly. Check your Minecraft profile for your current username.
2. Ask the admin to add you. The command is /whitelist add YourUsername. The server automatically resolves your UUID from Mojang's API.
3. If you changed your username recently: The whitelist stores UUIDs, not names. If you were added before a name change, you should still be whitelisted. However, if the admin added you by name after you changed it, they might have used the old name. Ask them to re-add you with the current name.
4. If the server is offline-mode: Offline-mode servers generate UUIDs differently from online-mode servers. If the server switched between online and offline mode, all whitelist entries become invalid. The admin must re-add everyone.
5. Check whitelist.json directly. The file is in the server root directory. Each entry has a UUID and a name. Verify your entry exists and the UUID matches your Mojang profile UUID.
6. Reload the whitelist. If the admin edited whitelist.json manually, they must run /whitelist reload for changes to take effect.

Common Causes

• Not added to the whitelist. The server has white-list=true or enforce-whitelist=true in server.properties and your name is not on the list.
• Username changed. The whitelist uses UUIDs, but the /whitelist add command looks up the UUID by name. If you changed your name, the admin might be trying to add the old name, which now resolves to a different UUID (or fails).
• Online/offline mode mismatch. UUIDs differ between online and offline mode. Switching modes invalidates the whitelist.
• Bedrock player on a Java server. GeyserMC adds a prefix (usually a .) to Bedrock player names. The admin must whitelist the prefixed name, like .BedrockPlayer.

Managing the Whitelist

Server admins can use these commands:

• /whitelist add <player> - Add a player
• /whitelist remove <player> - Remove a player
• /whitelist list - Show all whitelisted players
• /whitelist on - Enable the whitelist
• /whitelist off - Disable the whitelist
• /whitelist reload - Reload whitelist.json from disk

Setting enforce-whitelist=true in server.properties kicks players who are removed from the whitelist while online. Without this setting, already-connected players stay connected until they disconnect.

Whitelist File Format

The whitelist.json file is a JSON array of objects. Each object contains a UUID and a name:

[
  {
    "uuid": "12345678-abcd-1234-abcd-123456789012",
    "name": "PlayerName"
  }
]

If you edit this file manually, use a JSON validator to ensure the syntax is correct. A missing comma or bracket breaks the entire whitelist. After manual edits, run /whitelist reload in the server console for changes to take effect.

Whitelist Plugins for Advanced Control

If the vanilla whitelist is too limited for your needs, plugins like EasyWhitelist or AdvancedWhitelist offer features like temporary whitelist entries (auto-expire after a set time), application-based whitelisting through Discord bots, and bulk whitelist imports from a file or database. These plugins replace the vanilla whitelist system entirely.

FAQ

Can I whitelist myself?

Only server operators or the server console can run whitelist commands. If you are the server owner, use the server console.

Does the whitelist work with Velocity or BungeeCord?

Each backend server has its own whitelist. If you use a proxy, you can disable whitelists on backend servers and manage access through the proxy's permissions instead.

Why was I removed from the whitelist?

An admin removed you, or the whitelist file was reset. Contact the server admin to find out the reason and request re-addition if appropriate.

Can I whitelist a Bedrock player on a Java server using GeyserMC?

Yes, but Bedrock players have a prefix added to their name (usually a dot). Whitelist the prefixed name: /whitelist add .BedrockPlayerName. The exact prefix depends on your Geyser configuration. Check config.yml in the Geyser plugin folder for the username-prefix setting.

Need a server that handles all this? Astroworld Hosting, NVMe SSDs, Pterodactyl panel, DDoS protection on every plan.