How to Fix Whitelist Not Working in Minecraft

The Problem

Whitelist is enabled but non-whitelisted players can still join
/whitelist add works but player still cannot connect
Whitelist entries disappear after server restart

The Minecraft whitelist should restrict access to only approved players. When it fails, either everyone can join regardless of whitelist status, or correctly whitelisted players are still blocked. Both situations indicate a configuration or UUID mismatch issue.

Quick Fix

Check two things in server.properties: white-list=true and enforce-whitelist=true. Both must be true for the whitelist to fully work. After changing either, restart the server (reload is not sufficient for server.properties).

Step-by-Step Diagnosis

1. Verify server.properties settings. Open server.properties and confirm white-list=true. Also check enforce-whitelist=true, which kicks non-whitelisted players who are already online when removed from the list.
2. Restart after changing server.properties. Changes to server.properties require a full server restart. /whitelist reload only reloads whitelist.json, not the server.properties file.
3. Check whitelist.json format. Open whitelist.json in a text editor. It must be valid JSON. A misplaced comma or missing bracket breaks the entire file. Use a JSON validator to check.
4. Verify UUIDs. Each entry in whitelist.json has a UUID and a name. The UUID must match the player's actual Mojang UUID (for online-mode) or offline UUID (for offline-mode). Use mcuuid.net to look up the correct UUID.
5. Check online-mode setting. If online-mode=false, UUIDs are calculated differently than online mode. Re-add players with /whitelist add to ensure the correct UUID is used.
6. Proxy server configuration. If you use Velocity or BungeeCord, the whitelist on backend servers may not work as expected because connections come from the proxy, not directly from players. Manage the whitelist on the proxy level or disable it on backends.

Common Causes

• enforce-whitelist not enabled. With only white-list=true, the whitelist is checked on join but existing players are not kicked if removed. Setting enforce-whitelist=true adds enforcement.
• Invalid JSON in whitelist.json. A syntax error makes the entire whitelist unreadable. The server falls back to allowing everyone.
• UUID mismatch. If the server switched between online and offline mode, all UUIDs changed. The whitelist entries point to the old UUIDs. Re-add all players.
• Plugin overriding whitelist. Some plugins (like BungeeGuard, LuckPerms, or custom login plugins) can bypass or override the vanilla whitelist. Check plugin configurations.
• Whitelist file not saved. If you edit whitelist.json while the server is running and the server auto-saves, your edits are overwritten. Use /whitelist add commands instead of editing the file directly, or stop the server before editing.

FAQ

Why do whitelist entries disappear after restart?

The server rewrites whitelist.json on shutdown. If you edited the file while the server was running, your changes are overwritten. Always use /whitelist add commands or edit the file while the server is stopped.

Does the whitelist work with a proxy?

Backend servers behind Velocity/BungeeCord receive connections from the proxy's IP. The vanilla whitelist checks the player's UUID, which still works, but the proxy itself should handle access control for better reliability.

Can I whitelist an entire IP range?

The vanilla whitelist only supports individual player UUIDs. For IP-based access control, use a firewall rule or a plugin that supports IP whitelisting.

Debugging Whitelist Issues Step by Step

If the whitelist appears to not work at all, follow this checklist:

1. Open server.properties and verify both white-list=true and enforce-whitelist=true are set. Pay attention to the exact key name, it is white-list with a hyphen, not whitelist.
2. Restart the server (not just reload) after changing server.properties.
3. From the server console, run whitelist list and verify entries appear.
4. Try to join with a non-whitelisted account. If you are rejected, the whitelist works.
5. If non-whitelisted players can still join, check for plugins that might be bypassing the whitelist check. Disable plugins one at a time and test.
6. If you use a BungeeCord or Velocity proxy, ensure the backend servers have online-mode=false and the proxy has online-mode=true. In this configuration, the proxy handles authentication and the backend whitelist checks UUIDs forwarded by the proxy.

Whitelist Behavior Differences

The whitelist behaves differently depending on your server software:

• Vanilla / Spigot: The whitelist is checked during the login phase. If disabled at runtime with /whitelist off, the setting reverts to "off" in server.properties on the next restart unless manually changed back.
• Paper: Paper preserves the whitelist state across restarts correctly. It also supports the enforce-whitelist setting more reliably.
• Proxy servers: Backend servers behind a proxy receive pre-authenticated connections. The vanilla whitelist still works but verifies UUIDs forwarded from the proxy, not directly from Mojang's servers.

Need a server that handles all this? Astroworld Hosting, NVMe SSDs, Pterodactyl panel, DDoS protection on every plan.