Minecraft whitelist, op and ban commands
To let a friend in, run whitelist add NAME. To make someone an operator, run op NAME. To block a player, run ban NAME. Type them in the server console without a slash, or in game chat with a slash if you are already an operator. On Java Edition 26.3 a new server starts with the whitelist on, so nobody can join until you add them. The builder below writes the exact command.
For Java Edition 26.3. Command syntax, argument types, permission-level names and defaults come from the data the official 26.3 server generates (MEASURED, 2026-10-04); other facts are labelled secondary. We did not run a player session. Java Edition only: Bedrock uses different commands.
Command builder
Pick the action, type the player name, add a reason if the command takes one. You get the console form and the in-game form. If JavaScript is off, use the tables below.
Server console (no slash)
In game chat (with slash)
Examples
What the builder writes for common jobs:
| Goal | Server console | In game |
|---|---|---|
| Let a friend in | whitelist add Alex_2 | /whitelist add Alex_2 |
| Make a friend an operator | op Steve | /op Steve |
| Ban a griefer, with a reason | ban Mallory griefing the spawn | /ban Mallory griefing the spawn |
| Ban an address | ban-ip 203.0.113.7 spam | /ban-ip 203.0.113.7 spam |
| Disconnect a player who is idle | kick Jordan AFK too long | /kick Jordan AFK too long |
| Lift a ban | pardon Mallory | /pardon Mallory |
Whitelist
The whitelist is a list of players who may join. When it is on, anyone who is not on it, and is not an operator, is turned away at login.
Square brackets mean optional. Each command is the same in the console and in game; only the leading slash differs.
| Command | What it does | Needs |
|---|---|---|
| whitelist add <targets> | Puts a player on the whitelist. They can be offline when you run it. | Level 3 (admins) |
| whitelist remove <targets> | Takes a player off the whitelist. | Level 3 (admins) |
| whitelist on | Turns the whitelist on. | Level 3 (admins) |
| whitelist off | Turns the whitelist off. | Level 3 (admins) |
| whitelist list | Prints the names on the whitelist. | Level 3 (admins) |
| whitelist reload | Reads whitelist.json again from disk. Use it after editing the file by hand. | Level 3 (admins) |
The 26.3 default: the whitelist starts on
A fresh 26.3 server writes white-list=true in server.properties (MEASURED: the file the official 26.3 server generates on a clean folder, 2026-10-04). Before 26.3 the default was off (secondary source: the community wiki's history lists the change in an early 26.3 test build; we did not run an older server).
A new server has an empty whitelist and no operators (INFERRED: nobody has been added yet), so with the whitelist on it turns away every player, with a message that you are not on the whitelist (the default is MEASURED; the community wiki lists the disconnect messages, and players see them in their own language; that operators skip the whitelist is also from the wiki, secondary). The first command has to come from the server console (or your host panel's console): whitelist add YourName, or op YourName.
If you want an open server, run whitelist off in the console, or set white-list=false in server.properties and restart. For a private server of friends, leave it on.
The two server.properties keys
| Key | Default in 26.3 | What it does |
|---|---|---|
| white-list | true | Switches the whitelist on. With it on, a player who is neither on whitelist.json nor an operator is refused at login. |
| enforce-whitelist | false | With false, a reload of the list never disconnects anyone. With true, a reload also checks who is online, and anyone the new list leaves out is sent off the server. |
The defaults are MEASURED from the generated 26.3 file. How the two keys behave comes from the community wiki (secondary) and was not run in a session. The commands whitelist on and whitelist off switch the whitelist while the server runs (same source); we did not check whether they also rewrite the white-list key.
All keys of the file are explained on our server.properties page.
whitelist.json
The whitelist lives in whitelist.json in the server folder. Each entry holds a player name and a UUID, and the server checks the UUID, not the name (community wiki, secondary). If you edit the file by hand while the server runs, run whitelist reload afterwards (same source).
Why am I not whitelisted?
A message that you are not on the whitelist means the server found no entry for your account and you are not an operator. The causes, most common first:
- The whitelist is on and you are not on it. This is the normal case on a 26.3 server, where the whitelist starts on. An operator or the console runs whitelist add YourName.
- The wrong name was added. The server checks the account UUID (secondary). A typo can match a different, real account (INFERRED), and that account is let in instead of your friend. Run whitelist list, compare it with the real name, remove the wrong entry with whitelist remove and add the right one. A player who renamed their account still matches: the list may show the old name, but the UUID is the same (INFERRED from the same source). list uuids shows the UUID of each player who is online.
- The server runs in offline mode (online-mode=false). The community wiki (secondary) says that in offline mode each player's id is computed from the name they type, not taken from their Mojang account, so an entry made in online mode no longer matches. We have not reproduced it. Remove the entry and add the name again while the server runs in the mode you will keep. In offline mode the whitelist does not protect the server: anyone who types a listed name matches it (INFERRED from the same source). Keep online-mode=true.
- whitelist.json was edited by hand and not reloaded. Run whitelist reload in the console. Until then the server uses the list it already had in memory.
- It is a different refusal. A banned account gets a message that it is banned from the server, with the reason; a banned address gets one that says the IP address is banned (the community wiki lists these messages, secondary; players see them in their own language). If the message is about a ban, look at banlist.
Not a cause: operators skip the whitelist on Java Edition (community wiki, secondary). Not covered: players who join through a proxy or a Bedrock bridge, which we have not verified in a primary source. Bedrock Edition has its own command, /allowlist (Microsoft Learn).
Operators (op)
An operator is a player who may run server commands. /op adds the player to ops.json and /deop removes them. The level they get is the op-permission-level key of server.properties, 4 by default (the default is MEASURED; that /op uses the key comes from the community wiki, a secondary source).
| Command | What it does | Needs |
|---|---|---|
| op <targets> | Makes a player an operator. | Level 3 (admins) |
| deop <targets> | Removes operator status. | Level 3 (admins) |
Permission levels
The 26.3 command list names three levels: gamemasters, admins and owners (MEASURED). That they are levels 2, 3 and 4, and that a level includes everything the lower ones allow, comes from the community wiki (secondary). The table shows what the commands we extracted need; it covers 23 commands, not every command in the game.
| Level | Name | Commands that need it |
|---|---|---|
| 0 | (no requirement) | list. No operator needed. |
| 1 | (not named in the list) | None of the measured commands. The community wiki (secondary) says it lets a player build inside spawn protection. |
| 2 | gamemasters | gamemode, gamerule, defaultgamemode, difficulty, time, weather, seed. |
| 3 | admins | whitelist, op, deop, ban, ban-ip, pardon, pardon-ip, banlist, kick, setidletimeout. |
| 4 | owners | stop, save-all, save-off, save-on, publish. |
ops.json and op-permission-level
ops.json holds one entry per operator, with the player name and UUID, a "level" number and a "bypassesPlayerLimit" flag (community wiki, secondary). Change a level by editing the number. Among the commands we extracted there is none that reloads ops.json, so stop the server before you edit it and start it again afterwards (INFERRED).
With the default level 4, every operator can stop the server and use the save commands (MEASURED: those need owners). To keep that to yourself, set op-permission-level=3 and give level 4 by hand in ops.json. A level 3 operator can run /op (MEASURED: op needs admins) and the wiki says new operators get the level in op-permission-level (secondary), so lowering the default also keeps level 3 operators from creating level 4 operators (INFERRED).
Console or in game
The server console runs any command, with no slash and no operator status (INFERRED, standard behaviour; we did not test it). In game, chat commands start with a slash and need an operator of the right level.
The first operator of a new server is usually created from the console (or your host panel's console): op YourName. Editing ops.json while the server is stopped also works (community wiki, secondary). After that, operators can use the commands in game.
Safety
Only make operators of people you would trust with your keys. An operator can ban players, change who may join and, at level 4, stop the server. Give the lowest level that does the job, and use deop when someone no longer needs it. A level 3 operator can run deop too (MEASURED: deop needs admins), so such an operator can remove other operators; we have not checked whether that includes level 4 operators.
This page is about operators. For commands that give items, see our Minecraft command generator.
Bans, address bans and kicks
ban blocks an account, ban-ip blocks an address, kick only disconnects. All of them need level 3 (MEASURED). They are the Java Edition commands.
| Command | What it does | Needs |
|---|---|---|
| ban <targets> [<reason>] | Bans a player account. The reason is optional and is shown to the banned player. | Level 3 (admins) |
| pardon <targets> | Lifts the ban on a player account. | Level 3 (admins) |
| ban-ip <target> [<reason>] | Bans an IPv4 address, or the address of an online player if you give a name. | Level 3 (admins) |
| pardon-ip <target> | Lifts the ban on an IPv4 address. | Level 3 (admins) |
| banlist [players|ips] | Lists the bans. Add players or ips to show only one kind. | Level 3 (admins) |
| kick <targets> [<reason>] | Disconnects a player now. Not a ban: they can rejoin. | Level 3 (admins) |
| list uuids | Prints each online player with their UUID. | Anyone |
ban or ban-ip?
ban stores the player account: the wiki says it blocks the profile's UUID (secondary). The player cannot join with that account, but can with another one.
ban-ip stores an address. It blocks everyone who connects from it: a brother on the same router, a school, a shared proxy. It is a blunt tool, and addresses change. The wiki says it also accepts the name of an online player, and then bans that player's address (secondary); the player must be online. If your players join through a tunnel or proxy, that address may be the proxy's, and banning it can lock everyone out.
Only IPv4 addresses can be typed. The command list gives the address argument as a single Brigadier word, which ends at the first colon, so an IPv6 address is rejected with Brigadier's "Expected whitespace to end one argument" (MEASURED: a probe of the open-source Brigadier 1.3.11 library; the community wiki records the same limit as bug MC-97885, secondary). For a player on IPv6, the name form of ban-ip is the way to try; we have not tested it.
The reason and where bans are stored
The reason is everything after the name, spaces included, and the banned player sees it (secondary). Keep @ and § out of a reason: the game may read @ as a selector, and § gets a player disconnected from chat (community wiki, secondary). A command typed in game is limited to 256 characters (same source); for a longer one use the console.
Bans are stored in banned-players.json and banned-ips.json in the server folder (community wiki, secondary), so they survive a restart (INFERRED, because they are files). Edit them by hand only while the server is stopped (INFERRED).
pardon and pardon-ip lift a ban. banlist lists them, and banlist players or banlist ips shows one kind.
Troubleshooting
| What you see | Likely cause | What to do |
|---|---|---|
| The game says the command is unknown or incomplete | A typo, a missing argument, or you are not an operator of level 3 or higher. | Read the red part of the message. Try the same command in the server console. Check your level in ops.json. |
| The game says the player does not exist | The name is not a real Java account: a typo, or a Bedrock gamertag (secondary: in online mode the name must belong to a real account). | Check the exact spelling of the Java account name and try again. |
| The game says the selector includes entities | You used @e or @n where a player is needed. | Type the player name. |
| The game says the IP address is invalid or the player unknown | ban-ip got a badly written IPv4 address or a name that is not online. | Four numbers from 0 to 255, no leading zeros, or the name of a player who is online now. |
| "Expected whitespace to end one argument, but found trailing data" | An IPv6 address, or extra text, in an argument that takes one word. | IPv6 cannot be typed here. For ban-ip, try the name of the online player (untested). If you pasted an address with :port, remove the port. |
| The game says nothing changed because the player is already an operator, banned or whitelisted | The command did what you asked earlier. | Nothing. Use banlist, whitelist list or ops.json to check. |
| A message that you are not on the whitelist | The whitelist is on and the account is not on it. | See Why am I not whitelisted? above. |
| Edits to whitelist.json have no effect | The server still has the old list in memory. | Run whitelist reload. |
FAQ
How do I whitelist someone on my Minecraft server?
In the server console run whitelist add NAME, or in game /whitelist add NAME as an operator of level 3 or higher. They can be offline when you run it. Check with whitelist list.
Why am I not whitelisted on the server?
On Java Edition 26.3 (the version we checked) a new server starts with the whitelist on, so everyone who is not an operator or on the list is refused with a message that you are not on the whitelist. Ask the owner to run whitelist add with your exact account name. Other causes are a wrong name, an edit of whitelist.json that was not reloaded, and offline mode.
How do I turn the whitelist off?
Run whitelist off in the console, or set white-list=false in server.properties and restart. Turning it off lets anyone with the server address join.
How do I make someone an operator?
Run op NAME in the console, or /op NAME in game if you are already an operator. They get the level in op-permission-level, 4 by default. To remove the status, run deop NAME.
How do I ban a player, or ban an IP address?
ban NAME [reason] bans the account and ban-ip ADDRESS [reason] bans an IPv4 address, or the address of an online player if you give a name. Undo them with pardon NAME and pardon-ip ADDRESS.
Do these commands work on Bedrock Edition?
Not as written here. This page covers Java Edition. Bedrock uses /allowlist instead of /whitelist, and we have not checked the rest.
How we checked
The syntax, the argument types, the permission-level names and the defaults come from the data the official Minecraft Java Edition 26.3 server generates (MEASURED, 2026-10-04): its command list and its server.properties. We also ran a probe of the open-source Brigadier library. Other facts come from the community wiki, named as secondary here and read only to verify; we copied no wiki text. Labels used: MEASURED, VERIFIED FROM PRIMARY SOURCE, INFERRED and UNTESTED.
- Minecraft Wiki, /whitelist (secondary) (accessed 2026-10-04)
- Minecraft Wiki, permission level (secondary) (accessed 2026-10-04)
- Minecraft Wiki, player usernames (secondary) (accessed 2026-10-04)
- Minecraft Wiki, server: whitelist, operators, disconnect messages (secondary) (accessed 2026-10-04)
- Minecraft Wiki, /ban and /ban-ip (secondary) (accessed 2026-10-04)
- Microsoft Learn, /allowlist for Bedrock (primary, Bedrock only) (accessed 2026-10-04)
Unofficial tool. Not affiliated with, approved by or associated with Mojang or Microsoft. Minecraft is a trademark of Mojang.