Fix Whitelist Not Working on Minecraft Servers

How the Whitelist Works

The Minecraft whitelist is a JSON-based access control list stored in whitelist.json in your server root. When enabled, only players whose UUID and username appear in this file can join. The whitelist is controlled via server.properties with white-list=true (or enforce-whitelist=true for stricter enforcement) and managed with in-game commands.

Common Problem 1: Whitelist Enabled but Not Enforcing

If you set white-list=true but any player can still join, check enforce-whitelist in server.properties:

white-list=true
enforce-whitelist=true

The enforce-whitelist setting kicks players who are not on the whitelist when you run /whitelist reload or when they try to join. Without it, players already online stay connected even if removed from the list. This is the most frequent cause of minecraft whitelist not working reports.

Common Problem 2: UUID Mismatch (Online/Offline Mode)

Whitelist entries store both the player's name and UUID. If you switch between online-mode=true and online-mode=false, every player's UUID changes (online UUIDs are Mojang-assigned; offline UUIDs are name-derived). This means your existing whitelist entries become invalid.

Fix: After changing online-mode, clear the whitelist and re-add all players:

/whitelist remove OldEntry
/whitelist add PlayerName

Or delete whitelist.json and rebuild it from scratch.

Common Problem 3: Proxy Setups (BungeeCord / Velocity)

If you run a BungeeCord or Velocity proxy, the whitelist should be managed at the proxy level, not on individual backend servers. Backend servers in a proxy setup typically run online-mode=false, which changes UUID derivation. If the proxy whitelists a player but the backend also has whitelist enabled with different UUIDs, the player gets rejected.

Recommended setup:

• Enable whitelist on the proxy (BungeeCord: use a whitelist plugin; Velocity: configure in velocity.toml).
• Disable whitelist on backend servers.

Common Problem 4: Editing whitelist.json Manually

If you edit whitelist.json by hand and make a JSON syntax error (missing comma, extra bracket), the server silently fails to load the whitelist. Always use /whitelist add and /whitelist remove commands instead. If you must edit manually, validate the JSON with a linter before saving.

Common Problem 5: whitelist.json Not Reloading

Changes to whitelist.json only take effect after /whitelist reload or a server restart. If you added a player through the file but they still can't join, run:

/whitelist reload

Diagnostic Steps

1. Confirm white-list=true and enforce-whitelist=true in server.properties.
2. Run /whitelist list to see who is currently whitelisted.
3. Verify the player's UUID matches what is in whitelist.json (use a UUID lookup tool like namemc.com).
4. If using a proxy, check where the whitelist is enforced.
5. Restart the server after changes to server.properties.

Want to just play without the headaches? Join Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.