Whitelist, operators and bans on a Minecraft server

Three basic tools control who can join your server and what they can do there: the whitelist lets in only selected players, operators get all commands, and a ban blocks anyone who breaks the rules. You can do all of it from the console in the customer area or in the game.

You can also manage the whitelist, operators and bans without commands in the Players tab: while the server runs, the portal sends a console command; while it is stopped, it edits the files directly. A non-default operator level can only be set while the server is stopped.

Whitelist#

The whitelist is a list of players who are allowed to join. When it's on, the server turns everyone else away with the message You are not white-listed on this server! (Paper and Purpur always send You are not whitelisted on this server! in English). It's useful for private servers with friends, testing or closed events.

Turning on the whitelist#

1. Add yourself first so you don't lock yourself out (operators can always join, though):

   whitelist add <NICK>

   • whitelist add – adds a player to the whitelist. The player doesn't need to be online or to have ever joined before. The server looks up their account.
   • <NICK> – the player's in-game name, for example Steve.

   [12:00:01 INFO]: Added Steve to the whitelist

2. Add all other players with the same command.

3. Turn on the whitelist:

   whitelist on

   [12:00:05 INFO]: Whitelist is now turned on

   The whitelist applies immediately, and the server also writes white-list=true to server.properties, so it survives a restart.

You get the same result with the setting in the customer area: the Server properties tab › the Players group › turn on Whitelist › Save and restart.

Enforce whitelist#

When you turn on the whitelist, players who are currently connected and aren't on the list stay on the server. The Enforce whitelist option (enforce-whitelist in server.properties) kicks them when the whitelist reloads. Turn it on in the Server properties tab in the Players group.

Whitelist commands#

The list is saved in whitelist.json in the server root. Each player has a UUID (a unique account identifier) and a name in the file. We don't recommend editing it by hand; the commands are safer.

Bedrock players (Geyser and Floodgate)#

Add Bedrock Edition players with the Floodgate add-on's command. Type the name without the prefix:

fwhitelist add <NICK>

Floodgate adds a prefix to Bedrock players' names in the game (a dot by default, for example .Steve) so their names don't clash with Java players. The fwhitelist command adds the prefix for you. More in Crossplay with Bedrock.

Operators#

An operator (op) can use server commands according to their permission level. The default level is 4, which means every single command.

op <NICK>

[12:01:10 INFO]: Made Steve a server operator

deop <NICK>

[12:01:30 INFO]: Made Steve no longer a server operator

• op gives a player operator rights, deop takes them away. The change applies immediately.

Operator permission levels#

You set the level for new operators in the Server properties tab › Players › Operator permission level (op-permission-level, a value of 1–⁠4, default 4). The level of a specific operator is in the ops.json file:

[
  {
    "uuid": "<PLAYER_UUID>",
    "name": "Steve",
    "level": 4,
    "bypassesPlayerLimit": false
  }
]

• uuid – the unique account identifier. The server fills it in itself on op.
• name – the in-game name (just for reference; the UUID is what counts).
• level – level 1–⁠4 according to the table above.
• bypassesPlayerLimit – true means the operator can join even a full server.

Only edit the file while the server is stopped, otherwise the server overwrites it when saving.

Bans#

Example:

ban Griefer123 Griefing builds at spawn

[12:02:00 INFO]: Banned Griefer123: Griefing builds at spawn

When a banned player tries to join, they see You are banned from this server and the reason. Bans are saved in the banned-players.json and banned-ips.json files.

Temporary bans#

Vanilla Minecraft can't do temporary bans. With the EssentialsX plugin (Paper, Purpur), use:

tempban <NICK> <duration> [reason]

• <duration> – for example 30m (minutes), 12h (hours), 3d (days), 1w (week), 1mo (month). Combinations like 1d12h also work.
• Example: tempban Steve 3d Chat spam.

Installing EssentialsX is covered in Recommended plugins.

Kicking players (kick)#

kick <NICK> [reason]

Disconnects the player, but they can rejoin right away. Useful as a warning. Output: Kicked Steve: reason.

Online mode and security#

The Account authentication (online-mode) option in the Server properties tab decides whether the server checks with Mojang that a player owns a genuine account.

• On (recommended): every name belongs to a real account. The whitelist, op and bans work reliably.
• Off: anyone can join under any name, including operators' names. The customer area warns you about this: “With authentication off anyone can join under any name, including operators' names.” Turning it off only makes sense behind a proxy (Velocity) that does the authentication itself, see A server network with Velocity.

Verify it works#

• whitelist list lists the whitelisted players.
• banlist lists the bans.
• A player who isn't on the whitelist gets the whitelist message when trying to join.

Troubleshooting#

A player is on the whitelist but the server won't let them in#

• The name has a typo, or the player changed their name. Check whitelist list and add them again.
• A Bedrock player has to be added with fwhitelist add.
• The server runs with online-mode off and the whitelist contains the UUID of the genuine account. With authentication off, the player has a different UUID. Add them again.

That player does not exist#

The server couldn't find an account with this name at Mojang. Check the exact spelling of the name.

Nothing changed. The player is already an operator#

The player is already an operator. If you want to change their level, edit level in ops.json while the server is stopped.

The whitelist turned off after a restart#

You probably turned it on in the Server properties tab but didn't save, or you were editing server.properties at the same time and the server overwrote it on startup. Turn it on again with whitelist on and check that Whitelist is on in Server properties.

An unbanned player still can't join#

They probably also have an IP ban. Check banlist ips and remove it with pardon-ip <IP>. Temporary bans from EssentialsX are removed with unban <NICK>.

Further reading#

• Minecraft Wiki: whitelist (opens in a new window)
• Minecraft Wiki: ban (opens in a new window)
• Minecraft Wiki: permission levels (opens in a new window)
• Floodgate: features and fwhitelist (opens in a new window)