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.

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.

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.

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

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.

Questions about Fix Whitelist Not Working

What does Fix Whitelist Not Working come down to?

The Minecraft whitelist should restrict access to only approved players.

How do you begin Fix Whitelist Not Working?

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.

Which command does Fix Whitelist Not Working use?

The Minecraft whitelist should restrict access to only approved players. This guide uses /whitelist reload.

Where does Fix Whitelist Not Working store its settings?

Check two things in server.properties: white-list=true and enforce-whitelist=true.

What should you avoid while doing Fix Whitelist Not Working?

A misplaced comma or missing bracket breaks the entire file.