--- title: "Minecraft Whitelist and Ban Management" description: "Enable the Minecraft whitelist, edit whitelist.json and banned-players.json safely, avoid the UUID-versus-username trap, and set up temporary bans." url: "https://www.gameserverkings.com/knowledge-base/minecraft/whitelist-and-ban-management/" category: "Minecraft" category_url: "https://www.gameserverkings.com/knowledge-base/minecraft/" published: "2026-08-19T04:43:54.512Z" updated: "2026-08-19T08:23:27.224Z" source_format: "markdown" site: "GameServerKings" --- # 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](/knowledge-base/minecraft/admin-commands/). For what an operator is allowed to do once they are in, see [Minecraft Op Permission Levels](/knowledge-base/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. | File | What it does | Managed by | |---|---|---| | `whitelist.json` | The guest list. If the whitelist is on, only these players may connect | `/whitelist` | | `banned-players.json` | Accounts that are refused, by UUID | `/ban`, `/pardon` | | `banned-ips.json` | IP addresses that are refused | `/ban-ip`, `/pardon-ip` | | `ops.json` | Who has operator powers, and at what level | `/op`, `/deop` | > [!IMPORTANT] 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](/knowledge-base/minecraft/bedrock/) for the Bedrock side. ## Turning the Whitelist On There are two switches and they control different things. ```properties title="server.properties" 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: ```text title="Console — no slash needed" whitelist on whitelist off ``` ![The panel's Console tab, with the command input where whitelist and ban commands are typed]() > [!TIP] `/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. > [!WARNING] 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. > [!IMPORTANT] 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](/knowledge-base/minecraft/server-properties-reference/). ## Adding Players to the Whitelist The player does not need to be online, and does not need to have ever joined. ```text title="Console" 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: ```text title="Console output — the name could not be resolved" That player does not exist ``` with a matching warning in the log: ```text title="logs/latest.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: | Cause | Fix | |---|---| | The username is misspelled, or that account does not exist | Check the spelling. Minecraft usernames are 3–16 characters | | The server cannot reach Mojang's API | A network or DNS problem on the host, not a Minecraft problem | | The player renamed and you used their old name | Use their **current** name, or add them by UUID (below) | 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: ```json title="whitelist.json" [ { "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. The same trap catches paid access. A whitelist slot or a rank recorded against a username rather than a UUID breaks the day that player renames — [Minecraft Server Monetisation](/knowledge-base/minecraft/monetising-your-server/) covers keying purchases on the UUID instead, and what Mojang's guidelines let you charge for in the first place. ### 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: ```text title="Look up a UUID" https://api.mojang.com/users/profiles/minecraft/jeb_ ``` ```json title="Response" { "id" : "853c80ef3c3749fdaa49938b674adae6", "name" : "jeb_" } ``` > [!WARNING] 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:`. That has a blunt consequence: > [!CAUTION] 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: ```json title="usercache.json" [{"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. ```text title="Console — after editing whitelist.json in the File Manager" 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. > [!TIP] `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. | Command | What it does | |---|---| | `/ban [reason]` | Ban an account by UUID | | `/ban-ip [reason]` | Ban an IP address, or the IP of a named online player | | `/pardon ` | Unban an account | | `/pardon-ip
` | Unban an IP address | | `/banlist [players\|ips]` | Show the ban lists — with no argument it prints both | If you leave the reason out, the banned player sees `Banned by an operator.` > [!NOTE] `/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 ```json title="banned-players.json" [ { "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" } ] ``` ```json title="banned-ips.json" [ { "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. > [!CAUTION] 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: ```text title="EssentialsX" /tempban [reason] /tempbanip [reason] /mute [datediff] [reason] /kick [reason] /seen ``` 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. ```text title="Ban for three days, with a reason" /tempban Steve 3d Griefing spawn ``` > [!TIP] 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. > [!WARNING] 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](/knowledge-base/minecraft/java-plugins/) 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](/knowledge-base/minecraft/luckperms-permissions/). ## 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 ` 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 ` 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 1w `, 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](/games/minecraft/) and they are in the top-level listing alongside your world folder. ## What to Read Next - [Minecraft Server Commands](/knowledge-base/minecraft/admin-commands/) for the full command reference, including every `/whitelist` and ban subcommand in one table - [Minecraft Op Permission Levels](/knowledge-base/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](/knowledge-base/minecraft/server-properties-reference/) for `white-list`, `enforce-whitelist`, `online-mode` and the rest of the file - [How to install plugins for Minecraft Java Edition](/knowledge-base/minecraft/java-plugins/) for installing EssentialsX in the first place - [How to Set Up LuckPerms Permissions for Minecraft](/knowledge-base/minecraft/luckperms-permissions/) for wiring ban, kick and tempban permissions to moderator ranks - [Getting started with your Minecraft server](/knowledge-base/minecraft/java-getting-started/) for first boot and connecting - [Setting up your Bedrock Minecraft server](/knowledge-base/minecraft/bedrock/) for the Bedrock allowlist, which behaves differently --- Made with 💜 by GameServerKings