How do I turn on the whitelist on my Minecraft server?

Open server.properties in your hosting panel's File Manager and change white-list=false to white-list=true. Save the file and restart your server. Then add players with whitelist add Username in the console.

What happens when someone tries to join a whitelisted server they're not on?

They see a message saying 'You are not whitelisted on this server' and are immediately disconnected. They cannot connect at all until you add them with whitelist add Username.

Can I enable the whitelist without restarting the server?

Yes. Run whitelist on in the server console to enable it instantly without a restart. Use whitelist off to disable it the same way.

How do I add a player to the whitelist in Minecraft?

Run whitelist add Username in your server console (no slash) or /whitelist add Username in-game if you are an operator. The player doesn't need to be online when you add them.

How to Whitelist Your Minecraft Server in 2026 (Java & Bedrock)

By FreeGameHost Team • Updated May 2026 • 6 min read

A whitelist is the simplest way to keep your Minecraft server private — only players you approve can connect. Whether you're running a friends-only SMP or a small community server, this guide walks through enabling and managing the whitelist on a FreeGameHost server in under two minutes.

<2 minSetup time

Java& Bedrock

NoRestart needed to add players

Built-inNo plugins required

How to enable the whitelist
Adding players to the whitelist
Removing players from the whitelist
All whitelist commands (quick reference)
Toggling the whitelist without restarting
Bedrock Edition whitelist
enforce-whitelist explained
FAQ

How to enable the whitelist

The whitelist is controlled by a single setting in server.properties. It's off by default — here's how to turn it on.

Add yourself to the whitelist first

Before enabling the whitelist, add your own username so you don't lock yourself out. In the Console tab of your FreeGameHost panel, run:

whitelist add YourUsername

~10 seconds

Open server.properties

In your panel, go to File Manager and click on server.properties to open the editor.

~15 seconds

Enable the whitelist setting

Find the line that reads:

white-list=false

Change it to:

white-list=true

Click Save.

~20 seconds

Restart your server

Click Restart in your panel. Once the server is back online (look for Done in the console), the whitelist is active. Anyone not on the list will see "You are not whitelisted on this server."

~45 seconds

Always whitelist yourself before enabling. If you enable white-list=true without adding your own username first, you'll be locked out of your own server. Add yourself first via the console, then enable the setting.

Adding players to the whitelist

Players can be added at any time — they don't need to be online, and you don't need to restart the server after adding them.

Via the panel console (recommended)

whitelist add Steve
whitelist add Alex
whitelist add YourFriendHere
# Use their exact Minecraft Java username or Xbox gamertag (Bedrock)

From in-game

If you're an operator, you can add players without going to the panel:

/whitelist add FriendUsername
# Include the slash when running from in-game chat

Adding players who haven't joined yet. You can whitelist someone before they've ever joined the server — just use their exact username. Once added they can connect straight away without any extra steps.

Removing players from the whitelist

To remove someone's access, use whitelist remove. They'll be disconnected the next time they try to join (or immediately if enforce-whitelist is enabled — see below).

whitelist remove FriendUsername
# Console — no slash

/whitelist remove FriendUsername
# In-game — requires OP

To check who's currently on your whitelist:

whitelist list

All whitelist commands — quick reference

Command (console)	What it does
`whitelist on`	Enables the whitelist without a server restart
`whitelist off`	Disables the whitelist instantly — everyone can join
`whitelist add Username`	Adds a player to the whitelist
`whitelist remove Username`	Removes a player from the whitelist
`whitelist list`	Lists all whitelisted players
`whitelist reload`	Reloads `whitelist.json` from disk — useful if you edited the file manually

In-game vs console commands: All commands above work in the console without a slash. When running the same commands in-game, prefix them with / — e.g. /whitelist add Username.

Toggling the whitelist without restarting

You don't always need to restart to change whitelist status. The whitelist on and whitelist off commands update the setting live:

whitelist on
# Enable immediately — no restart needed

whitelist off
# Disable immediately — opens server to everyone

This is handy when you want to temporarily open your server for new players to join, then lock it down again once they're in.

Bedrock Edition whitelist

Bedrock servers use the same whitelist system, but with a couple of differences:

Use the player's Xbox gamertag instead of a Java username
Gamertags are case-sensitive — match them exactly
The whitelist file is named whitelist.json on most Bedrock server types (some, like Nukkit, call it white-list.txt)

whitelist add XboxGamertag
# Bedrock: use the full Xbox gamertag exactly as it appears

What is enforce-whitelist?

There's an additional setting in server.properties called enforce-whitelist. Here's the difference:

enforce-whitelist=false (default): Players already connected when you enable the whitelist can stay in the game. Only new connection attempts are checked against the list.
enforce-whitelist=true: When you run whitelist on or reload the whitelist, anyone currently connected who is not on the list is immediately kicked.

For most friend-group servers, the default (false) is fine. Set it to true if you're managing a community server and want instant enforcement when you update the whitelist.

# In server.properties:
enforce-whitelist=true

Frequently asked questions

Can I edit the whitelist file directly?

Yes. The whitelist is stored in whitelist.json in your server's root folder. You can edit it via the File Manager in your panel. After saving changes, run whitelist reload in the console to apply them without restarting. The file format looks like this:

[
{"uuid": "player-uuid", "name": "Steve"},
{"uuid": "player-uuid", "name": "Alex"}
]

Does the whitelist work if online-mode is false?

Yes, but with a caveat. In offline mode (online-mode=false), Minecraft doesn't verify player identities against Mojang's servers. This means anyone can join using any username, including whitelisted ones. Whitelist by username still works, but it's less secure. For a genuinely private server, keep online-mode=true.

A friend changed their Minecraft username — do I need to re-whitelist them?

For Java Edition, the whitelist is stored by UUID — the unique ID behind the username — so a name change doesn't break it. They can still connect after changing their username. For Bedrock (Xbox gamertag), a gamertag change means you'll need to remove the old name and add the new one.

Can I use a plugin for more advanced whitelisting?

Yes. If you need features like temporary whitelisting, per-world whitelists, or a web-based invite system, plugins like AdvancedWhitelist or EasyWhitelist extend the built-in system significantly. Both are available on SpigotMC and work on Paper servers.

How do I turn off the whitelist completely?

Run whitelist off in the console to disable it instantly. Or open server.properties, set white-list=false, and restart. Either approach opens the server to all players.

Need a private server for your friend group? Get started free — 4 GB RAM, 24/7 uptime, no credit card.

Create Free Server →

Free tools & hosting: server.properties generator