How to Whitelist a Minecraft Server (Java, Bedrock Allowlist, Aternos and Hosts)

Short answer for how to whitelist a Minecraft server on Java: run /whitelist add PlayerName from the server console or in game as an op, and make sure the whitelist is on. That's it. Three lines cover most people:

• whitelist on
• whitelist add PlayerName
• whitelist list

A whitelist is a guest list. Only the players on it can join, which is exactly what you want for a private server for friends. Without one, anyone who gets hold of your address can wander in, and r/aternos has the griefed-build stories to prove it. Below: Java commands, the files behind them, Bedrock's version (it's called an allowlist), Aternos, generic hosts, crossplay names, and what to do when someone gets the "not whitelisted" kick.

Is the whitelist already on?

Maybe, and this changed recently. Older guides say the whitelist is off until you turn it on. As of Java 26.3, the Minecraft Wiki lists the white-list setting as true by default. So on a current Java server your friends may be getting turned away right now because nobody's on the list yet. On an older version you switch it on yourself with /whitelist on.

Java whitelist commands

These all work from the server console. In game you need to be an op with permission level 3. If you're still setting the server up, start with my guide to making a Minecraft server.

If the server is in online mode (the default), type the player's real account name. Ops can always join a Java server even if they're not on the list, so once you've made yourself an op you don't need to add yourself.

whitelist.json and server.properties

Every Java entry lives in whitelist.json in your server folder, one uuid and name per player. The server checks the UUID, not the name, when someone joins. If you edit the file by hand while the server's running, run /whitelist reload or your changes won't show up.

Two keys in server.properties matter:

• white-list: true uses the list, false lets everyone in. Changing the file needs a server restart to take effect.
• enforce-whitelist: defaults to false. When it's true and the whitelist is on, anyone online who isn't listed gets kicked once the whitelist reloads. When it's false, players already online stay put.

Bedrock: the allowlist

Bedrock Dedicated Server calls it an allowlist (it was renamed from "whitelist" in Bedrock 1.18.10). The file is allowlist.json, and the switch in server.properties is allow-list. In the default file for BDS 1.26.62.1 it's true. To turn it off, set allow-list=false and restart the server.

The commands mirror Java's: allowlist add, allowlist remove, allowlist list and allowlist reload. Put names with spaces in double quotes. Two differences from Java to know about:

• Operators don't get a free pass. On Bedrock every player has to be on the list, ops included.
• Entries are matched by XUID, with the gamertag in name.

Setting up Bedrock from scratch? My Bedrock server guide covers the base install.

How to whitelist on Aternos

Aternos does it with buttons, not commands. If you're picking a host, my free Minecraft server hosting roundup compares the options, and is Aternos safe covers the trust side.

1. Open the Options page and switch on Whitelist.
2. Open the Players page, type the player's name and click add.

Anyone not on the list gets disconnected. On a Bedrock server Aternos calls it the allowlist, and there's a catch: you can only add players while the server's running, and they need to join for the first time before the server stops. If you're on Java and want non-listed players kicked the moment you switch the list on or remove someone, enforce-whitelist in server.properties does that.

Other hosts and panels

Every host lays its panel out differently, but the tools you need are almost always there. Look for the console tab and run the same commands from the Java table above (or the allowlist ones for Bedrock). Or open the file manager, edit whitelist.json or server.properties, then run whitelist reload or restart. Some panels also have a players or whitelist tab, which is just a friendlier front end for the same thing.

Crossplay: Bedrock players on a Java server

If your Java server runs Geyser so Bedrock players can join, their names carry a prefix on the server, so their plain gamertag won't match a whitelist entry. Aternos's example: add a . in front of the name, so a player called AternosTutorials goes in as .AternosTutorials. Check your own setup's docs for what prefix it uses. The full setup is in my crossplay Minecraft server guide, and how to play Minecraft with friends covers the other ways to get everyone in the same world.

"Not whitelisted" kick: troubleshooting

The kick says, roughly, that you're not on this server's whitelist. If it's you or a friend hitting it, go down this list:

• Typo in the name. Easy to miss. Run whitelist list and compare letter by letter.
• You edited the file but didn't reload. After changing whitelist.json by hand, run whitelist reload.
• Online mode changed. With online-mode off, Java checks the whitelist against an offline UUID built from the username. Entries added when the server was online use real UUIDs and won't match, and the reverse is true too. Fix it by removing the players and adding them again after you've settled on one mode. Keep online-mode on unless you have a reason; the wiki says to turn it off only for servers that aren't connected to the internet.
• The Bedrock player hasn't joined yet (Aternos). They have to join once before the server stops, as above.
• Crossplay prefix missing. A Bedrock player on a Geyser server needs the prefix in their entry.
• Whitelist is on and you didn't know. On Java 26.3, it's on by default. Add your friends or set white-list=false if you want an open server.