Minecraft Whitelist and Ban Management

Every public Minecraft server eventually needs a door policy. The whitelist decides who is allowed in at all; the ban lists decide who is kept out after they have already caused trouble. Both are built into vanilla Java Edition, both are stored as plain JSON files next to your world, and both bite people in the same two places: the difference between a username and a UUID, and what happens when you edit those files by hand while the server is running.

This guide covers the whitelist and the ban lists on a Java Edition server. For the command syntax itself — every subcommand, in one table — see Minecraft Server Commands. For what an operator is allowed to do once they are in, see Minecraft Op Permission Levels.

Whitelist vs Ban List vs Op List

Four files in your server root control access. They are separate systems and they are checked in a specific order.

A ban beats a whitelist

Being on the whitelist does not exempt anyone from the ban lists — the ban list supersedes any whitelisting in place. Being an op, on the other hand, does bypass the whitelist on Java Edition: operators can always connect while the whitelist is active, even when their profile is not in whitelist.json. Bedrock Edition works the other way round, where players must be on the allowlist regardless of operator status. See Setting up your Bedrock Minecraft server for the Bedrock side.

Turning the Whitelist On

There are two switches and they control different things.

white-list=false
enforce-whitelist=false

• white-list turns the whitelist on. With it enabled, anyone not in whitelist.json is refused at the connection screen.
• enforce-whitelist decides what happens to players who are already online when the whitelist file reloads. Left at false, they stay connected until they disconnect on their own. Set to true, non-whitelisted players are kicked when the server reloads the whitelist.

You can flip the whitelist from the panel's Console instead of editing the file:

whitelist on
whitelist off

/whitelist on edits server.properties for you

This is the part most guides miss. Running whitelist on does not just change a runtime flag — the server writes white-list=true straight back into server.properties, so the setting survives a restart. Running whitelist off writes white-list=false back the same way. You never need to edit that line by hand, and if you edit it by hand while the server is running, the next /whitelist on or off will overwrite you.

Turning the whitelist on does not remove anyone already playing

whitelist on only filters new connections. If a griefer is online right now, whitelisting them out will not disconnect them — kick or ban them instead. enforce-whitelist=true is what makes existing non-whitelisted players get removed when the list reloads.

The Default Is Changing — But Has Not Changed Yet

On every released version of Java Edition today, a freshly generated server.properties contains white-list=false. We generated one on a clean 26.2 server to confirm it.

Mojang has changed that in development. The white-list property becomes true by default in 26.3, a change that first appeared in 26.3 Snapshot 2. As of this writing 26.3 has not been released — the current release is 26.2 and 26.3 is still in snapshots.

Plan for the flip, do not assume it

When 26.3 ships, a brand-new server will start whitelisted, and the first symptom is that nobody can join a server that looks perfectly healthy in the console. If you create a server on 26.3 or later and connections are refused, check white-list before you check anything else. Until then, a new server is open by default and you must turn the whitelist on yourself. For the full key-by-key breakdown of the file, see Minecraft server.properties: The Complete Reference.

Adding Players to the Whitelist

The player does not need to be online, and does not need to have ever joined.

whitelist add jeb_
whitelist remove jeb_
whitelist list

Adding an offline player is not a purely local operation. The server has to turn the username into a UUID, and it does that by calling Mojang's profile API. On a server with online-mode=true and working outbound internet this is invisible. When it fails, you get this:

That player does not exist

with a matching warning in the log:

[Server thread/WARN]: Couldn't find profile with name: zqxwvu9910
MinecraftClientHttpException[type=HTTP_ERROR, status=404, ...]

Three things produce that message, and they need different fixes:

Adding a player who is already online always works, because the server already knows their UUID.

The UUID Trap

This is the single most common source of "I whitelisted them and it still says not whitelisted."

A Minecraft account is identified by its UUID, not its name. Names can be changed, and old names can eventually be taken by somebody else. Every access list — whitelist, bans, ops — is keyed on the UUID. The name field alongside it is a human-readable label the server keeps up to date when it can; it is not what the check runs against.

Here is what a real whitelist entry looks like, generated by whitelist add jeb_ on a 26.2 server:

[
  {
    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
    "name": "jeb_"
  }
]

Two consequences follow, and they point in opposite directions:

• A player who renames keeps their access. Their UUID has not changed, so the whitelist entry still matches. The name in the file just goes stale until the server next refreshes it. Nothing is broken.
• A player who renames cannot be added by their old name. The lookup resolves whatever account holds that name now — which is either nobody, giving you "That player does not exist", or somebody else entirely, which silently whitelists a stranger.

That second case is not hypothetical. A Java player may change their username once every 30 days, and a released username becomes claimable by anyone else after 37 days. Names on your server that nobody has logged in under for a month or two are exactly the ones worth re-checking.

Adding Someone by UUID

If you need to whitelist an account you cannot resolve by name, look the UUID up and write the entry yourself. Mojang's public endpoint takes a username:

https://api.mojang.com/users/profiles/minecraft/jeb_

{
  "id" : "853c80ef3c3749fdaa49938b674adae6",
  "name" : "jeb_"
}

The API returns the UUID without hyphens; the file needs it with hyphens

whitelist.json, banned-players.json and ops.json all store UUIDs in hyphenated 8-4-4-4-12 form. The API returns the same 32 hex characters unhyphenated. Pasting the API value straight into the file produces an entry that never matches anyone. Split it as 853c80ef-3c37-49fd-aa49-938b674adae6.

Offline Mode Changes the Rules Completely

With online-mode=false, there is no Mojang account to check, so the server invents a UUID from the username instead — a version-3 UUID built from the MD5 hash of the string OfflinePlayer:<username>. That has a blunt consequence:

In offline mode, the username is the identity

Because the UUID is derived from the name, changing a name creates a completely different player — new inventory, new position, no whitelist entry, no ban. Worse, anyone can type any username at the login screen, so bans and whitelists can be walked straight past. online-mode=false is not a way to run a public server safely; it exists for isolated LAN setups. Leave it at true.

usercache.json

Alongside those files the server keeps usercache.json, a local name-to-UUID cache so it does not have to call Mojang for every lookup:

[{"uuid":"853c80ef-3c37-49fd-aa49-938b674adae6","name":"jeb_","expiresOn":"2026-09-18 23:37:15 -0500"}]

Entries carry an expiresOn roughly a month out. It is a cache and nothing else — deleting it is harmless, and it is never the file to edit when fixing an access problem.

Editing whitelist.json by Hand

Editing the file directly is supported, and for bulk work — pasting in thirty applicants at once — it is far quicker than thirty console commands. There is one rule.

whitelist reload

The server holds the whitelist in memory. Until you reload it, your edits exist on disk and nowhere else. We tested this on 26.2: after appending a second entry to the file, whitelist list still reported one whitelisted player. After whitelist reload it reported two.

enforce-whitelist fires on reload

That reload is exactly the moment enforce-whitelist=true acts on. If you remove someone from whitelist.json and reload with enforcement on, they are kicked immediately rather than at their next login.

Banning Players

The ban commands need permission level 3 and only exist on a dedicated server.

If you leave the reason out, the banned player sees Banned by an operator.

/ban-ip has two real limitations

Its target must be either a literal IP address or the name of a player who is online right now — it cannot look up the last known address of an offline player. And it cannot ban an IPv6 address at all; this is a long-standing limitation, not a configuration problem on your side. If a persistent attacker connects over IPv6, ban the account rather than the address.

What a Ban Record Actually Contains

[
  {
    "uuid": "61699b2e-d327-4a01-9f1e-0ea8c3f06bc6",
    "name": "Dinnerbone",
    "created": "2026-08-18 23:37:15 -0500",
    "source": "Server",
    "expires": "forever",
    "reason": "Testing the record format"
  }
]

[
  {
    "ip": "198.51.100.7",
    "created": "2026-08-18 23:37:15 -0500",
    "source": "Server",
    "expires": "forever",
    "reason": "Test ip ban"
  }
]

source records who issued the ban — Server for a ban typed into the console, or the operator's name for one typed in chat. expires is the literal string forever for a permanent ban.

Never Edit the Ban Files on a Running Server

The whitelist has /whitelist reload. The ban lists have no equivalent. Typing banlist reload returns Incorrect argument for command — the subcommand does not exist.

That leaves the ban lists in a worse position than the whitelist. The server loads them at startup, keeps them in memory, and rewrites the whole file from memory every time a ban changes. Anything you added by hand in the meantime is not in memory, so it is not in the file the server writes.

We confirmed this on 26.2. With the server running, we appended a second entry to banned-players.json by hand. banlist players still reported one ban. A single /ban on an unrelated player then rewrote the file — and the hand-added entry was gone, with no error and nothing in the log.

Stop the server before editing banned-players.json or banned-ips.json

The safe sequence is: stop the server from the panel, edit the file in the File Manager, start it again. On a running server, use /ban and /pardon and let the server own the file. This is not a "usually fine" situation — the overwrite is silent and total.

Temporary Bans

Here is the frustrating part of vanilla. The ban record has a real expires field and the server honours it — a banned player is even told when their ban lifts. But no vanilla command can set an expiry. /ban writes forever and offers no duration argument.

We verified the record side of that directly: with the server stopped, we wrote a ban with "expires": "2026-12-25 12:00:00 -0500", restarted, and the server accepted it, listed it in /banlist players, and normalised the timestamp into its own timezone form. So a timed ban is entirely possible — there is just no command for it.

That is why practically every server that moderates seriously installs a plugin. On a Paper/Spigot/Purpur server, EssentialsX is the usual answer:

/tempban <player> <datediff> [reason]
/tempbanip <player> <datediff> [reason]
/mute <player> [datediff] [reason]
/kick <player> [reason]
/seen <player>

The duration is written as a combined string: y years, mo months, w weeks, d days, h hours, m minutes, s seconds. All of 3d, 1d12h and 2w are valid.

/tempban Steve 3d Griefing spawn

EssentialsX tempbans live in banned-players.json

EssentialsX does not keep a private ban database for this. It writes through the server's own ban list, so a tempban lands in banned-players.json with a real expires timestamp — the same record vanilla already understands. Uninstalling the plugin does not release anyone; the bans stay and simply become un-editable from chat again.

EssentialsX registers its own /ban, /kick and /unban

EssentialsX ships commands called ban, banip, kick, unban and unbanip, and it declares pardon and pardonip as aliases of its own /unban and /unbanip. The behaviour is close enough that most people never notice, but if a moderation command starts behaving differently after a plugin install — a different message, a different permission being checked — this is why. Effectively every EssentialsX command also has an explicit e-prefixed alias (/eban, /ekick, /etempban) if you want to be certain which one you are calling. See How to install plugins for Minecraft Java Edition for installing EssentialsX in the first place.

EssentialsX also has an essentials.tempban.exempt permission and a maximum tempban length, so you can let junior moderators issue day-long bans without letting them issue year-long ones. Wiring that to a rank is a permissions job — see How to Set Up LuckPerms Permissions for Minecraft.

A Note on the Management API

Newer Java servers ship a JSON-RPC management API over WebSocket, disabled by default and configured through the management-server-* keys in server.properties. It exposes the allowlist and both ban lists as proper endpoints, and — unlike the chat commands — its ban objects accept an optional ISO-8601 expires timestamp, so it can create timed bans natively.

It is aimed at people building tooling rather than at day-to-day moderation, and it needs a 40-character secret plus an explicit origin allowlist before it will accept a connection. If you are scripting bans from a Discord bot or a web panel, it is the supported route. If you are moderating by hand, the commands above are all you need.

Common Issues

• "You are not white-listed on this server!" for someone you just added. Run whitelist list and read it. If the name is missing, the add failed — most often a rename or a typo. If the name is there, they are connecting with a different account than you think.
• You added players to whitelist.json and nothing changed. You did not run whitelist reload.
• A ban you added by hand vanished. The server was running. See above; redo it with /ban, or stop the server first.
• /ban-ip says the target is invalid. It is not a literal IP and the player is not online. Ban the account instead.
• The whitelist is on but ops can still get in. That is intended on Java Edition. Ops bypass the whitelist.
• Everyone got kicked when you edited the whitelist. enforce-whitelist=true and the file reloaded. That is what the setting does.
• Nobody can join a brand-new 26.3-or-later server. Check white-list — the default flips to true in 26.3.

FAQ

Do whitelisted players need to be added again after they change their name?

No. The whitelist matches on UUID, which does not change with a rename. The stored name goes stale but the entry keeps working.

How do I whitelist someone who has never joined and is not online?

whitelist add <name> works for offline players — the server resolves the name through Mojang's API. If that fails, look the UUID up yourself and add a hyphenated entry to whitelist.json by hand, then run whitelist reload.

Can I ban a player who has never joined my server?

Yes. /ban <name> resolves the name to a UUID the same way the whitelist does, so you can pre-emptively ban an account you have only heard about.

How do I ban someone for one week?

Not with vanilla commands — /ban always writes a permanent ban. Install EssentialsX and use /tempban <player> 1w <reason>, which writes a real expiry into banned-players.json.

What is the difference between kicking and banning?

/kick disconnects a player once; they can reconnect immediately. /ban adds them to banned-players.json and refuses every future connection until pardoned. Use a kick to break up an argument, a ban to end a relationship.

Should I use online-mode=false so friends without accounts can join?

No. It replaces real account verification with a username the client simply asserts, which makes both the whitelist and the ban list trivially bypassable. It also gives every player a name-derived UUID, so a rename wipes their inventory. If you need private access, use the whitelist with online-mode=true.

Why can I not ban an IPv6 address?

/ban-ip does not support IPv6. It is a long-standing limitation. Ban the account rather than the address.

Where are these files on my server?

In the server root, next to server.properties — open the File Manager on your Minecraft server and they are in the top-level listing alongside your world folder.

What to Read Next

• Minecraft Server Commands for the full command reference, including every /whitelist and ban subcommand in one table
• Minecraft Op Permission Levels for which level each of these commands needs, and how to grant a moderator level 3 without level 4
• Minecraft server.properties: The Complete Reference for white-list, enforce-whitelist, online-mode and the rest of the file
• How to install plugins for Minecraft Java Edition for installing EssentialsX in the first place
• How to Set Up LuckPerms Permissions for Minecraft for wiring ban, kick and tempban permissions to moderator ranks
• Getting started with your Minecraft server for first boot and connecting
• Setting up your Bedrock Minecraft server for the Bedrock allowlist, which behaves differently

Made with 💜 by GameServerKings