Minecraft Whitelist Generator

What is a Minecraft whitelist?

This Minecraft whitelist generator turns a list of usernames into a whitelist.json file. Paste up to 100 names above, press the lookup button, and the tool asks the Mojang API for each player's UUID. Players that exist go into the file. Names that do not match a Java Edition account are listed under the form and left out, so the file never has a broken entry.

A whitelist is the list of players allowed to join your server. When it is turned on, anyone who is not on the list gets "You are not white-listed on this server!" and is disconnected before they reach the world. It is the simplest way to keep a private SMP private: friends, a school class, a Discord community that applies through a form, or a test server that only staff should see.

The whitelist lives in whitelist.json, next to server.properties in the server's main folder. Vanilla, Spigot, Paper, Purpur, Fabric and Forge servers all use the same file and the same format.

The whitelist.json format

whitelist.json is a JSON array with one object per player:

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

• uuid is the player's account UUID in the dashed 8-4-4-4-12 form. This is what the server checks when someone joins
• name is the player's name at the time they were added. The server does not use it to match players. It is there so people reading the file know who each entry is

Because the server matches on the UUID, a player who changes their name stays whitelisted. The old name stays in the file until the server rewrites it, which does no harm. It also means an entry with a correct name and a wrong UUID does not work at all. That is why this tool looks up every UUID instead of letting you type names only.

An empty whitelist is written as []. A server with white-list=true and an empty whitelist.json lets only operators in, as the section on operators explains.

How to turn the whitelist on

Two settings in server.properties control the whitelist:

• white-list=true turns the whitelist on. With false, the default, the file is ignored and anyone can join
• enforce-whitelist=true kicks players who are already online but not on the list whenever the whitelist is reloaded or turned on. With false, a player removed from the list can stay until they disconnect

For a private server you usually want both set to true. The server.properties generator has a switch for each of these two settings, so you can turn both on there. It also covers online-mode and max-players, which matter for the whitelist too.

The full steps for a new server:

1. Generate whitelist.json with the tool above and download it
2. Stop the server
3. Put the file in the server's main folder, the one that holds server.properties, replacing the old one
4. Set white-list=true and enforce-whitelist=true in server.properties
5. Start the server and check the console for errors

On most hosting panels the main folder is the root of the file manager. The file has to be called exactly whitelist.json, all lowercase, with no .txt added by the editor.

Whitelist commands

You do not have to edit the file by hand. The server has commands that change the list and save the file for you. In the console type them without the slash; in the game chat, an operator of level 3 or higher types them with the slash:

• /whitelist on and /whitelist off turn the whitelist on or off and write the change to server.properties
• /whitelist add <name> looks the player up and adds them
• /whitelist remove <name> removes them
• /whitelist list shows every name on the list
• /whitelist reload reads whitelist.json from disk again

The commands are fine for one or two players. For a whole community, a generated file is faster: paste the names from your application form or Discord channel, download the file, and replace the old one.

Editing the file while the server runs

The server keeps the whitelist in memory and writes it to whitelist.json every time a command changes it. If you replace the file while the server is running and someone then runs /whitelist add, the server writes its old list plus the new player, and your upload is gone.

There are two safe ways to put a new file in place:

• Stop the server, replace the file, and start it again
• Replace the file, then run /whitelist reload straight away in the console, before anyone changes the list

After a reload, enforce-whitelist=true kicks online players who are no longer on the list.

Operators and the whitelist

Operators can always join a whitelisted server, even when they are not in whitelist.json. The server checks ops.json first. So you do not need to add your admins to both files, and removing someone from the whitelist does not lock them out if they are still an operator.

If a player you removed can still join, check ops.json. The ops.json generator writes that file with each operator's permission level, and its article explains what each level allows.

Online mode, offline mode and UUIDs

This tool writes online-mode UUIDs, the ones Mojang gives every Java Edition account. They are right for any server with online-mode=true, which is the default and what you should use on a public server.

A server with online-mode=false does not ask Mojang who a player is. It makes a different UUID from the player's name, and those offline UUIDs never match the ones in a file made with this tool. The result is a whitelist that lets nobody in. The UUID lookup tool explains how online and offline UUIDs are made and how to tell them apart: online UUIDs have a 4 at the start of the third group, offline ones a 3.

There is one common setup where online-mode=false is correct and the online UUIDs still work: a backend server behind a Velocity or BungeeCord proxy with player info forwarding turned on. The proxy checks the player with Mojang and forwards the real UUID to the backend, so the backend sees the same UUIDs this tool returns. If forwarding is off, the backend falls back to offline UUIDs and the whitelist stops working. The Velocity config builder and the BungeeCord config generator set forwarding up on the proxy side.

Whitelists on a proxy network

Velocity and BungeeCord do not have a whitelist of their own. You have two choices:

• Whitelist every backend. Copy the same whitelist.json to each server and turn the whitelist on in each server.properties. This works as long as forwarding is set up, and it lets you whitelist a staff-only server separately from the rest
• Use a proxy whitelist plugin. A plugin on the proxy checks players before they reach any backend, and you keep one list for the whole network. Plugins keep their own list format, so check whether yours can import a whitelist.json

For most small networks the first choice is enough. Generate the file once and upload it to each backend.

Custom kick message

Vanilla's "You are not white-listed on this server!" message cannot be changed. On Spigot, Paper and Purpur you can set your own in spigot.yml under messages.whitelist, for example to point people to your Discord where they can apply. The spigot.yml generator has the field in its Messages section.

Bedrock players with Geyser and Floodgate

Bedrock players who join through Geyser do not have Java accounts, so the Mojang API cannot find them and the tool lists them as not found. Floodgate gives each of them a UUID made from their Xbox account instead. To whitelist them, use Floodgate's /fwhitelist add <name> command, or have them join once and then add them with the server's own commands. Their names start with Floodgate's prefix, a . by default.

Common mistakes

• Leaving white-list=false. The file does nothing until the whitelist is turned on in server.properties or with /whitelist on
• Uploading while the server runs. The server writes its own copy back and your changes are lost. Stop the server first or run /whitelist reload
• Using online UUIDs on an offline server. Nobody matches and nobody can join. Check online-mode first
• Broken JSON. A missing comma or an extra one after the last entry makes the file unreadable. The generated file is always valid JSON; if you edit it by hand afterwards, run it through a JSON validator before uploading
• Wrong file name or folder. whitelist.json must sit in the main folder, not in world/ or plugins/, and some editors save it as whitelist.json.txt
• Old name lists. Servers before 1.7.6 used white-list.txt with one name per line. Current versions convert that file once and then only read whitelist.json, so adding names to the old text file does nothing
• Assuming names are enough. The name field is only a label. An entry with the right name and a made-up UUID lets nobody in

Keeping the list up to date

A whitelist works best when adding people is quick. Some habits that help on a growing server:

• Keep the source list somewhere you can edit, such as a pinned message or a text file, and regenerate the file from it when many people join at once
• Use /whitelist add in the console for single players between regenerations
• Remove players who left with /whitelist remove, so a sold or shared account cannot come back
• Pair the whitelist with a permissions plugin so new players start with limited rights. The LuckPerms setup guide shows how to give a default group to everyone who joins, and the anti-grief plugins guide covers protection for the day a trusted player turns out not to be

The post on how small SMPs grow looks at how long-running community servers handle applications and whitelists as they get bigger, and the optimal server.properties settings post covers white-list together with the other settings worth checking on a new server.