Minecraft Server Whitelist: How to Make Your Server Invite-Only

A Minecraft server whitelist is a list of the only players allowed to join. Turn it on with whitelist on, add each friend with whitelist add Name, and everyone else gets turned away at the door. This guide covers the commands, the whitelist.json file, the difference between white-list and enforce-whitelist, Bedrock players on Geyser, and how to fix the “You are not white-listed on this server!” message.

Everything here applies to Java Edition servers running Vanilla, Paper, Purpur or another Paper fork. A short section near the end covers Bedrock Dedicated Server, which uses an allowlist instead.

How a Minecraft server whitelist works

When someone connects, the server checks the player's UUID (the unique ID of their Minecraft account) against the list stored in whitelist.json, in the main server folder. If the UUID is not there, the connection is refused. According to the Minecraft Wiki, three details matter:

• Operators always get in. On Java Edition, server operators can connect while the whitelist is active even if they are not listed. Bedrock Edition is stricter: everyone, operators included, must be on the allowlist.
• The list checks UUIDs, not names. A friend who changes their username stays on the list. That is also why the server needs online-mode=true to look names up correctly (more on that below).
• The default changed in 2026. Since Java Edition 26.3, the white-list property is true by default in a new server.properties. On older versions it starts as false, so check yours before you assume anything.

How to make a Minecraft server invite-only

If you already have a server running, this takes about two minutes. If you do not have one yet, start with how to make a Minecraft Java server and come back.

1. Open the server console. On TheGameHosting, open your server in the panel and choose Console. Commands typed there run with full rights and need no slash.
2. Type whitelist add YourName to add yourself first, with your exact Java username.
3. Add each friend with whitelist add FriendName. They do not need to be online.
4. Type whitelist on to turn the list on. The console answers “Whitelist is now turned on”.
5. Type whitelist list and check that every name is there and spelled right.
6. Open server.properties and confirm white-list=true, so the list is on after the next restart too. Add enforce-whitelist=true if you also want players who are not on the list kicked when the list changes.

whitelist add YourName
whitelist add FriendName
whitelist on
whitelist list

Adding yourself before turning the list on is a habit worth keeping. Operators get in anyway, but if you remove your own OP later you would be locked out of your own world.

Minecraft whitelist commands

All of these need permission level 3, so a player must be an operator to use them in chat with a slash (/whitelist add Steve). In the console you type them without the slash. If you are not OP yet, our guide on how to OP yourself on a Minecraft server shows how.

The failure replies are useful too. “Player is already whitelisted” means the name is on the list already, and “Whitelist is already turned on” means there is nothing left to switch.

white-list vs enforce-whitelist

Both settings live in server.properties, and people mix them up all the time.

Without enforce-whitelist, removing someone with whitelist remove keeps them in the game until they disconnect; they just cannot come back. With enforce-whitelist=true, an unlisted player is kicked when you turn the whitelist on or remove them from it (PaperMC documentation), and after the server reloads the whitelist file (Minecraft Wiki). If you are closing a public server to friends only, turn on both.

The server reads server.properties when it starts, so restart after you edit it.

white-list=true
enforce-whitelist=true
online-mode=true

Editing whitelist.json by hand

whitelist.json sits in the root of the server folder, next to server.properties and ops.json. Each entry has the player's uuid (in hyphenated format) and name:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch"
  }
]

Editing the file is handy when you move a list from an old server or want to paste many players at once. Two rules: keep the JSON valid (commas between entries, no comma after the last one), and run whitelist reload in the console afterwards, because the server keeps the list in memory and does not notice outside changes until you reload it. If you are unsure of a UUID, use whitelist add Name instead and let the server fill it in.

On TheGameHosting you edit the file in the panel's Files tab, save, then type whitelist reload in Console. No FTP client needed.

Fix "You are not white-listed on this server!"

This is the message a player sees when the whitelist is on and their account is not on it. On Paper and Spigot servers the wording is slightly different, “You are not whitelisted on this server!”, and you can change it with messages.whitelist in spigot.yml. If a friend gets it, go through these causes in order:

1. They are not on the list. Run whitelist list. If the name is missing, run whitelist add Name.
2. The name was misspelled. The list stores the UUID of the account you typed. A typo can add the wrong account or none at all. Remove the bad entry and add the exact username again.
3. You edited the file but did not reload. Changes in whitelist.json do nothing until you run whitelist reload or restart.
4. The JSON is broken. A missing comma or bracket makes the file unreadable. Check the console for errors at startup and fix the file in Files.
5. They play on Bedrock. A Bedrock player joining through Geyser has a different name and UUID. See the next section.
6. The server runs in offline mode. With online-mode=false, the server matches an offline UUID made from the name, so entries added in online mode will not match.

If you just want everyone to get in again, whitelist off removes the restriction right away. Remember to set white-list=false in server.properties too, or check that it is false, so the list does not come back after a restart.

A player who cannot reach the server at all, with no whitelist message, has a connection problem, not a whitelist problem.

Whitelist Bedrock players with Floodgate

If your Java server lets console and phone players in with Geyser and Floodgate, those players have no Java account, so the regular whitelist add will not find them by name. Floodgate ships its own command for this. The GeyserMC wiki describes fwhitelist as the command to use for adding or removing Floodgate players from whitelist.json:

fwhitelist add BedrockGamertag
fwhitelist remove BedrockGamertag

• You do not need to type the username prefix. Floodgate adds one to Bedrock names (a dot by default, set with username-prefix in its config.yml), but fwhitelist handles it for you.
• You can also add a player by their Floodgate UUID, for example fwhitelist add 00000000-0000-0000-0009-01f64f65c7c3.
• For staff who are not OP, the permission node is floodgate.command.fwhitelist.

If Geyser is not set up yet, follow let Bedrock players join your Java server with Geyser first.

Running Bedrock Dedicated Server instead?

A pure Bedrock server calls it an allowlist. The property is allow-list in server.properties, the file is allowlist.json, and the command is allowlist add Name. There is no on or off subcommand on Bedrock, and operators must be on the list like everyone else.

Online mode and the whitelist

With online-mode=true (the default), every player is verified against Minecraft's account servers, so a name on your list really belongs to that account. With online-mode=false, the whitelist checks an offline UUID built from the username. Anyone who types a listed name in an unofficial launcher gets that same UUID, so the list stops being a lock. The Minecraft Wiki recommends offline mode only for servers that are not connected to the internet. If you are weighing it anyway, read Minecraft offline mode servers before you switch.

Keep the invite-only server online 24/7

A whitelist keeps strangers out, but it only works while the server is up. If it runs on your own PC, the world closes when you turn the computer off, and you have to open ports on your router so friends can connect. On TheGameHosting the server runs on our hardware in Dallas or Amsterdam, with an AMD 9950X or 7950X3D CPU and NVMe storage, so it stays online when your PC is off and nobody touches your router.

Everything in this guide happens in one panel: Console for the whitelist commands, Files to edit whitelist.json and server.properties, and Backups to save a copy before you change anything. Users lets you give a co-owner access to the panel without sharing your account. DDoS protection is included on every plan, and there is no charge per player slot. Plans start at $1.90 USD per month on the Minecraft server hosting page, and you can compare every RAM size on our game server plans.

Your server is ready in about 60 seconds after payment. Pick a plan on Pricing, add your friends with whitelist add, and share the address and port shown in your panel only with them.

FAQ

Hosting for this game

• Minecraft server hostingOne plan, 60+ games · from $1.90 USD/month