How to set up whitelisting on a Minecraft server

Understanding Whitelisting in Minecraft

Whitelisting, often referred to as allowlisting in Minecraft Bedrock Edition, is a crucial security feature for private multiplayer servers. It provides a simple yet effective mechanism to control who can access your server, ensuring that only approved players are able to connect. When whitelisting is active, the server acts as a gatekeeper, checking every incoming connection against a pre-defined list of player accounts. If a player’s username or UUID (Unique Universal Identifier) is not on this list, their connection will be rejected, and they will typically receive a message stating, “You are not whitelisted on this server.”

The primary purpose of implementing a whitelist is to maintain a secure and private gaming environment. This prevents unauthorized users, potential griefers, or simply unwanted players from joining your server. It’s an ideal solution for servers hosted among friends, family, or a small, trusted community.

For Minecraft Java Edition, the whitelist configuration is primarily managed through a file named whitelist.json, which is located in the server’s root directory. A key distinction in Java Edition is that players with operator (OP) status are automatically exempt from the whitelist by default, meaning they can connect even if their name isn’t explicitly on the list.

In contrast, Minecraft Bedrock Edition adopted the term “allowlist” starting from version 1.18.10. This list is stored in a file called allowlist.json. A significant difference here is that Bedrock Edition’s allowlist is stricter: players, including those with operator status, must be explicitly added to the allowlist to connect. There is no automatic bypass for operators.

Setting Up Whitelisting for Minecraft Java Edition

Implementing a whitelist on a Java Edition server involves a few straightforward steps, ensuring only your chosen players can join.

Step 1: Enable the Whitelist

The first step is to activate the whitelist feature on your server. You have two main methods for doing this:

• Via Server Console or In-game Command:
  • If you have direct access to your server’s console (e.g., through a hosting panel or a command prompt running the server), simply type /whitelist on and press Enter.
  • Alternatively, if you are an OP (operator) on the server, you can type the same command, /whitelist on, directly into the in-game chat and execute it. This will immediately enable the whitelist without needing a server restart.
• Via server.properties file:
  • This method requires you to stop your Minecraft server first to prevent data corruption.
  • Locate the server.properties file in your server’s root directory.
  • Open this file with a plain text editor (like Notepad, Notepad++, or VS Code).
  • Find the line that reads white-list=false.
  • Change this line to white-list=true.
  • Save the file and then restart your Minecraft server for the changes to take effect.

Step 2: Add Players to the Whitelist

Once the whitelist is enabled, you need to populate it with the names of the players you wish to grant access to.

• Via Server Console or In-game Command:
  • This is the easiest and most recommended method. For each player you want to add, type the command /whitelist add <playername> into the server console or in-game chat (if you have OP privileges).
  • For example, to add a player named “Steve”, you would type /whitelist add Steve. The server will automatically resolve the player’s unique UUID and add them to the whitelist.
  • Repeat this command for every player you want to include.
• Via whitelist.json file:
  • This method is more advanced and should be used with caution, typically only when direct command access is not feasible or for bulk additions.
  • First, stop your server to avoid issues.
  • Locate the whitelist.json file in your server’s root directory.
  • Open it with a JSON-aware text editor. The file contains an array of JSON objects, each representing a whitelisted player with their UUID and name.
  • To add a player, you must manually insert a new JSON object like this: {"uuid": "PLAYER_UUID", "name": "PLAYER_NAME"}. You will need to find the player’s UUID beforehand using an external UUID lookup service (e.g., a Minecraft UUID lookup website).
  • After saving the whitelist.json file, you must run the command /whitelist reload in the server console (or in-game if OP) to apply the changes without a full server restart.

Step 3: Verify the Whitelist

To confirm that all intended players have been successfully added to your whitelist, you can use a simple command:

• Via Server Console or In-game Command:
  • Type /whitelist list into the server console or in-game chat.
  • This command will display a list of all currently whitelisted player names, allowing you to quickly check your entries.

Step 4: Optional Whitelist Enforcement

For immediate removal of non-whitelisted players, you can enable whitelist enforcement.

• Via server.properties file or Command:
  • Set enforce-whitelist=true in your server.properties file (requires server restart).
  • Alternatively, use the command /whitelist enforce in the server console or in-game. This command will kick any currently connected players who are not on the whitelist without requiring a server restart.

Setting Up Allowlisting for Minecraft Bedrock Edition

Bedrock Edition’s allowlist functions similarly to Java’s whitelist but has some key differences, particularly regarding operator access.

Step 1: Enable the Allowlist

Enabling the allowlist in Bedrock Edition is usually done through your server’s configuration.

• Via Server Panel:
  • If you are using a hosting provider, navigate to their “Config Files” or “Server Settings” section in your control panel.
  • Look for a setting related to “Whitelisting” or “Allowlisting” and enable it.
  • Save your changes and then restart your server to apply the new configuration.
• Via Server Console:
  • You can also enable the allowlist by typing allowlist on into your server’s console. This command should be run after the server configuration file has been set to enable allowlisting.

Step 2: Add Players to the Allowlist

Adding players to the Bedrock allowlist is primarily done via console commands.

• Via Server Console:
  • Type allowlist add "playername" into the server console for each player you wish to add.
  • It is highly recommended to put quotation marks around the player’s name, especially if it contains spaces or special characters, to ensure it is parsed correctly. For example, allowlist add "Cool Gamer".
  • For crossplay servers (where Java and Bedrock players might connect via a proxy like GeyserMC), Bedrock players might need to join the server at least once before the allowlist is enabled. This ensures their name is properly registered. Additionally, a period prefix might be required for the command in some crossplay setups, like allowlist add .[player].
  • Remember, unlike Java Edition, operators in Bedrock Edition are not automatically exempt and must be explicitly added to the allowlist.

Step 3: Verify the Allowlist

To check who is on your Bedrock allowlist, use the following command:

• Via Server Console:
  • Type allowlist list into the server console.
  • This will display all player names currently on your Bedrock server’s allowlist.

Important Tips for Whitelisting/Allowlisting

To ensure a smooth experience when managing your server’s access, keep these tips in mind:

• Operator Privileges: Always ensure you have operator (OP) privileges on the server if you intend to use whitelist/allowlist commands directly in-game. Without OP status, these commands will not execute.
• Username Accuracy: Double-check the spelling of player usernames when adding them to the whitelist or allowlist. A single typo will prevent the player from joining.
• Reload After Manual Edits (Java Edition): If you manually edit the whitelist.json file in Java Edition, you must run the /whitelist reload command in the console. Forgetting this step means your changes won’t be applied, and players won’t be able to join until the server is restarted or the command is executed.
• Bedrock Allowlist Order: For Bedrock Edition, it’s generally best practice to enable the allowlist setting in your server properties or configuration file before attempting to use in-game or console commands to add players. This establishes the framework for the allowlist to function correctly.
• Server Panels: If your server is hosted by a third-party provider, take advantage of their server management panel. Many panels offer streamlined interfaces for whitelisting/allowlisting, often including graphical user interfaces that simplify adding and removing players, and handling server restarts or reloads.

Common Mistakes to Avoid

Even experienced server administrators can sometimes fall victim to simple oversights. Being aware of these common mistakes can save you a lot of troubleshooting time:

• Forgetting to Enable the Whitelist/Allowlist: A common error is adding all players but forgetting to actually turn the whitelist/allowlist “on.” Always ensure you’ve executed the /whitelist on or allowlist on command, or set the corresponding server property to true.
• Incorrect Player Usernames: This is perhaps the most frequent issue. A misspelled username will prevent a player from connecting, even if they are technically “on the list” with the wrong spelling. Always confirm the exact username.
• Not Reloading After whitelist.json Edits: For Java Edition, if you’ve directly modified the whitelist.json file, failing to run /whitelist reload will mean your changes aren’t active, and players won’t be able to join.
• Lack of OP Permissions: Attempting to use whitelist/allowlist commands in-game without having operator (OP) privileges will result in an error message and the command not executing. Ensure you are Opped or use the server console.
• Bedrock Edition Operator Exemption Misconception: For Bedrock Edition, remember that operators are not automatically exempt from the allowlist. If your server is allowlisted, you must explicitly add all operators to the allowlist, just like any other player.
• “Not Whitelisted” Despite Being on the List: If a player reports being unable to join with the “You are not whitelisted” message, even though you’ve confirmed their name is on the list, try these troubleshooting steps:
  • Remove the player from the list using /whitelist remove <playername> (or allowlist remove "playername").
  • Re-add them using /whitelist add <playername> (or allowlist add "playername").
  • Run a /whitelist reload (Java) or ensure the allowlist is re-enabled (Bedrock).
  • As a last resort, restart the entire Minecraft server. This often resolves any lingering caching or configuration issues.