Whitelist a Minecraft server

What Whitelisting Does

A whitelist restricts your server so that only approved players can connect. Anyone not on the list sees a "You are not whitelisted on this server" message and cannot join. Whitelisting is useful in several scenarios: running a private server for friends, beta testing new features before a public launch, hosting invite-only events, or locking down during an emergency (like a bot attack or exploit). It is the simplest and most effective access control mechanism available, and every server operator should know how to enable and manage it.

Vanilla Whitelist Setup

Minecraft includes a built-in whitelist that requires no plugins. To enable it, edit server.properties:

white-list=true
enforce-whitelist=true

The white-list=true setting activates the whitelist on the next server restart. The enforce-whitelist=true setting kicks any currently online player who is not on the whitelist, without this, players who joined before whitelist activation remain connected even if they are not whitelisted.

After changing the config, restart the server. Now manage the whitelist with these commands from the console or as an operator in-game:

/whitelist add PlayerName     <-- adds a player
/whitelist remove PlayerName  <-- removes a player
/whitelist list               <-- shows all whitelisted players
/whitelist reload             <-- reloads whitelist.json from disk
/whitelist on                 <-- enables whitelist without restarting
/whitelist off                <-- disables whitelist without restarting

The /whitelist on and /whitelist off commands let you toggle the whitelist without editing files or restarting, which is useful for quick lockdowns during emergencies.

Understanding whitelist.json

When you add a player to the whitelist, Minecraft stores their name and UUID in whitelist.json in the server root directory. The format looks like this:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  },
  {
    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
    "name": "jeb_"
  }
]

You can edit this file directly if you need to bulk-add players. After editing, run /whitelist reload to apply changes without restarting. The UUID is what actually matters, player names can change, but UUIDs are permanent. If a player changes their Minecraft name, their UUID-based whitelist entry still works.

For Bedrock players using Floodgate, the UUID format is different (Floodgate UUIDs start with 00000000-0000-0000-). You can whitelist Bedrock players by name using the Floodgate prefix: /whitelist add .BedrockPlayerName (assuming the default . prefix).

LuckPerms-Based Access Control

For more sophisticated access control, LuckPerms can serve as an alternative or supplement to the vanilla whitelist. Instead of using the built-in whitelist, you can:

1. Create a permission node that controls server access, such as server.join.
2. Use a plugin like LuckPerms' built-in restrictions or a lightweight gate plugin that checks for a permission on login.
3. Grant server.join to specific players or groups.

This approach integrates with your existing permission hierarchy. Want to let all members of the "donor" group bypass the whitelist? Grant the group the permission node. Want to add someone? Add them to a group that has the node. It is more flexible than the flat whitelist.json list, especially on larger servers with role-based access needs.

Maintenance Mode Plugins

If you need a more user-friendly whitelist experience, especially during server maintenance or beta testing, use a maintenance mode plugin like Maintenance (by kennytv). These plugins:

• Show a custom MOTD (Message of the Day) in the server list indicating the server is in maintenance.
• Display a custom kick message explaining why the server is temporarily closed.
• Allow specific players or permission groups to bypass the maintenance lockout.
• Work on single servers and proxy networks (BungeeCord, Velocity, see our proxy guide).

Maintenance mode is different from a permanent whitelist. Use the whitelist for ongoing access control (private server, invite-only). Use maintenance mode for temporary lockdowns (updating plugins, testing new features, fixing a critical bug).

When to Use a Whitelist

Whitelisting is not just for private servers. Here are common scenarios where a whitelist adds value:

• Beta testing: Before launching a new season or major update, whitelist the server and invite a small group of testers. They catch bugs and provide feedback before the general player base encounters issues. Open the whitelist when testing is complete.
• Private SMP: For a friends-only server, the whitelist is the primary security layer. Combine it with WorldGuard spawn protection and you have a secure, low-maintenance setup.
• Events: Running a tournament or special event? Whitelist registered participants so random players don't interfere. Remove the whitelist after the event ends.
• Emergency lockdown: If your server is being targeted by bots or a griefing group, enable the whitelist immediately with /whitelist on. This stops all unauthorized access while you address the issue. It is the fastest way to secure a server under attack.
• Gradual rollout: Launching a new server? Start with a whitelist and add players in waves. This lets you monitor performance and catch issues before the server is at full capacity.

Automating Whitelist Management

On servers with an application process (where new players submit a form or apply through Discord), manually running /whitelist add for every approved applicant gets tedious fast. Automating this saves hours of staff time per week on active servers. The most common approach is using RCON (Remote Console) to send whitelist commands programmatically. RCON is built into every Minecraft server, enable it in server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=your-secure-password-here

Once RCON is enabled, a Discord bot or web application can send whitelist add PlayerName commands to the server whenever an application is approved. Popular Discord bots like MCRcon or custom bots built with discord.js can handle this. The workflow becomes: player applies through a form, staff clicks "approve" in Discord, the bot sends the whitelist command, and the player is notified they can join. No manual console access needed.

For a self-service approach, some servers use a Pterodactyl API integration where approved players trigger their own whitelist addition through a web portal after their application is accepted. The Pterodactyl API exposes a command endpoint that can run any console command, including whitelist commands, provided you authenticate with an API key. This is more advanced to set up but creates a fully hands-off experience for staff.

Whitelist Best Practices

• Keep a backup of your whitelist.json file. If it gets corrupted or accidentally cleared, you don't want to re-add hundreds of players manually.
• Use enforce-whitelist=true so that removing a player from the whitelist kicks them immediately rather than letting them stay until they disconnect.
• For servers with applications (apply-to-join), automate whitelist additions through a Discord bot or web form that runs the whitelist command via RCON.
• Periodically review your whitelist and remove inactive players. A bloated whitelist is not a performance concern but makes management harder.
• Document your whitelist policy so staff know when to add, remove, or override whitelist restrictions.
• If you run a crossplay server with Geyser and Floodgate, remember that Bedrock players have different UUIDs and prefixed names. Test whitelisting a Bedrock player to make sure the process works before advertising crossplay support on a whitelisted server.