Shulkerboxes

Guides

How to Whitelist Friends on a Minecraft Java Server

Last checked: 7 October 2026

Become an operator, type /whitelist on, then /whitelist add <name> for each friend. Your friend does not need to be online. The list is saved in whitelist.json, and white-list=true in server.properties keeps it on after a restart. Anyone not on the list cannot connect, and operators can always join.

The short answer

On a Minecraft: Java Edition server, the whitelist is a list of players allowed to join. These steps work on any server where you can run commands, as of 7 October 2026:

  1. Make yourself an operator. In the server console, type op YourName. The whitelist command needs permission level 3, and operators get level 4 by default.
  2. Turn the whitelist on: /whitelist on.
  3. Add each friend by their Java Edition username: /whitelist add Steve. They do not need to be online, and you can list several names.
  4. Check the list: /whitelist list.
  5. To keep it on after a restart, make sure white-list=true is set in server.properties.

Typed in chat, a command starts with /. Some host consoles take it without the slash; Minehut’s help center says so for its Live Console.

Every /whitelist command

CommandWhat it does
/whitelist onTurns the whitelist on. Players not on it can no longer connect.
/whitelist offTurns the whitelist off. Anyone with the address can connect again.
/whitelist add <name>Adds a player. The player does not need to be online.
/whitelist remove <name>Removes a player. The player does not need to be online.
/whitelist listShows everyone on the whitelist.
/whitelist reloadReads whitelist.json from disk again, after you edit the file by hand.

All six need permission level 3 on Java Edition, and the command only exists on a dedicated server, not in singleplayer or a world opened to LAN. On Bedrock Edition the same feature is called the allowlist, and the command is /allowlist.

Turn it on in server.properties

The /whitelist on command changes the setting while the server runs. The setting itself lives in server.properties, next to the server jar:

  • white-list=true turns the whitelist on, using the names in whitelist.json. Since Java Edition 26.3 it is true by default on a new server, so a fresh server already refuses strangers.
  • enforce-whitelist=true kicks players who are online but not on the list when the server reloads the whitelist. It is false by default, which means removing someone does not kick them until they disconnect.

Edit server.properties while the server is stopped, then start it again.

The whitelist.json file

The server keeps the list in whitelist.json, a JSON array with one entry per player. Each Java Edition entry has two fields: uuid, the player’s UUID in hyphenated form, and name, their username. For example: [{"uuid": "550e8400-e29b-41d4-a716-446655440000", "name": "Steve"}].

The whitelist matches players by UUID, not by name, so a friend who changes their username stays on the list. That is also why /whitelist add is easier than editing the file: the server looks up the UUID for you. If you do edit the file while the server is running, type /whitelist reload for the change to take effect.

Removing a friend

Type /whitelist remove Steve. What happens next depends on enforce-whitelist:

  • If it is false (the default), Steve stays connected until he leaves, then cannot rejoin.
  • If it is true, Steve is kicked once the server reloads the whitelist. Aternos’s help article says that with enforce whitelist on, players not on the list are kicked as soon as you turn the whitelist on or remove them.

To keep someone out even if the whitelist is later turned off, ban them: /ban Steve. The ban list overrides the whitelist, and /pardon Steve lifts it. Both need permission level 3.

What a player not on the list sees

A player who is not whitelisted cannot connect. Their game shows the message “You are not whitelisted on this server!” Nothing else happens: they are not banned, and adding their name lets them in on the next try.

Two exceptions are worth knowing. On Java Edition, operators can always connect, even if they are not on the list. And on a server with online-mode=false (a “cracked” server), the whitelist checks a UUID made from the username, so anyone who types your friend’s name can get in.

How hosts handle it

Each host puts the same feature in a different place. Prices and limits below are as of 7 October 2026.

  • Aternos. Its help article says you enable the whitelist in the server’s options, then add players by name in the “players” section. Bedrock players who join through Geyser need a . in front of their name. Aternos blocks automated fetches, so this guide read the article through an Internet Archive snapshot dated 4 October 2025.
  • Minehut. Its help article lists four commands: /whitelist on, /whitelist off, /whitelist add and /whitelist remove, and says to leave out the slash in the dashboard’s Live Console. Minehut’s help center refused our fetch today, so this guide read it through an Internet Archive snapshot dated 14 July 2025.
  • Realms. A Realm has no whitelist command because nobody can join without an invite. On Java Edition, the owner invites a player by name from the Realm’s settings, and the invited player accepts it from the Realms screen. Realms for Java costs $7.99 USD a month for you and 10 players at a time, with up to 10,000 invited friends.
  • Shulkerboxes. Each server has a “Who can join” setting with two choices: “Only players on your list”, the default, or “Anyone with the address”. You add friends by their Java Edition username on the server page, and remove or block them in Settings. Only players on the list can be made operators.

When the whitelist does not work

  • Friend still cannot join. Check the spelling with /whitelist list. A Java Edition username is not the same as a Microsoft account email or a Bedrock gamertag.
  • You edited whitelist.json and nothing changed. Run /whitelist reload, or restart the server.
  • A removed player is still online. Turn on enforce-whitelist, or kick them with /kick.
  • Strangers still get in. Check that the whitelist is on (white-list=true) and that online-mode is true.
  • “Unknown command” in singleplayer. The whitelist is a server feature. A world opened to LAN does not have one.

For the rest of running a server for a group, see running a server for your Discord friends and server rules for friends.

Where Shulkerboxes fits (and doesn't)

On Shulkerboxes you do not type whitelist commands: a new server lets in only players on your list, and you add friends by username on the server page.

Shulkerboxes is free Minecraft: Java Edition hosting for a friend group, with no ads, no credit card and no port forwarding. The server sleeps when empty and wakes when a friend joins, ready in about a minute, and friends can join while the owner is offline. It is invite-only with a waitlist and open in the US, Spain, Germany, Mexico and Brazil, and your saved world is yours to download. It is free because gameplay on every server is recorded and used to build de-identified AI training datasets that are licensed to other companies (full explanation). Servers run Paper with built-in homes and /tpa; modpacks and custom plugins are not supported, and Bedrock players cannot join, so if your group needs those, pick a host that supports them, such as Aternos.

Have an invite code? Enter it on the home page. No invite yet? Join the waitlist and we will save you a spot.

FAQ

How do I whitelist a friend on my Minecraft server?

As an operator, type /whitelist on, then /whitelist add followed by your friend’s Java Edition username. They can join straight away. Set white-list=true in server.properties so it stays on after a restart.

Does my friend need to be online to be whitelisted?

No. The Minecraft Wiki says the player does not need to be online for /whitelist add or /whitelist remove.

Do operators need to be on the whitelist?

Not on Java Edition. Operators can always connect when the whitelist is on. On Bedrock Edition, every player must be on the allowlist, operators included.

Why can a player I removed still play?

Removing a name does not kick anyone unless enforce-whitelist is true in server.properties. Turn it on, or use /kick.

Can I use a whitelist in singleplayer or on LAN?

No. The /whitelist command is for dedicated servers only. A world opened to LAN has no whitelist.

What is the difference between a whitelist and a ban?

A whitelist lets in only the names on it. A ban blocks one player even when the whitelist is off, and it overrides the whitelist. /pardon lifts a ban.

Where is the whitelist file?

It is whitelist.json, in the same folder as server.properties. Each entry has the player’s UUID and name. Run /whitelist reload after editing it by hand.

Sources

All Minecraft Wiki and minecraft.net pages were fetched on 7 October 2026. Aternos and Minehut’s help center refused automated fetches that day, so their articles were read through the Internet Archive snapshots named below.

Written by the Shulkerboxes team.