Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →If a Minecraft whitelist is not working, first identify the edition: Java Edition uses /whitelist and whitelist.json, while Bedrock Dedicated Server uses /allowlist and allowlist.json. Then verify that access control is enabled, add the player with the server command, reload after any file edit, and test with a non-operator account. Java online-mode versus offline-mode identity changes and Bedrock gamer-tag formatting are the other frequent causes of a valid-looking entry being rejected.
Prefer not to run the server on your own PC? Godlike.Host offers hosted Minecraft Java servers with free DDoS protection and up to three free backups a day.
The steps below separate Java and Bedrock so you do not apply the wrong command or edit the wrong file.
As an Amazon Associate I earn from qualifying purchases.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick diagnosis: match the symptom to the likely cause
| What you observe | Most likely checks |
|---|---|
| Nobody is blocked, including people who are not listed | Confirm the whitelist or allowlist is enabled; check startup scripts, control panels, proxies, or automation that may disable it. |
| One listed Java player cannot join | Re-add the name with /whitelist add PlayerName, check spelling and identity mode, reload, and compare the server log with the entry. |
| An unapproved player can join Java | Check that white-list=true is active and that the test account is not an operator. Java operators can connect without appearing in whitelist.json. |
| Changes work until the server restarts | You may be editing a different server directory, a container volume is not mounted, or the server cannot write the file you changed. |
| A Bedrock player is ignored after editing the file | Verify the exact gamer tag and Bedrock schema, then run /allowlist reload. |
First, identify the edition and server software
Commands and file names are not interchangeable. A Java server normally has server.properties and whitelist.json, and its console accepts /whitelist. Bedrock Dedicated Server uses allowlist.json and the /allowlist command family. A hosting panel may label these controls differently, but the underlying edition still determines the syntax.
Java Edition dedicated server
Use Java instructions if players connect with Java Edition to a Java server jar such as the standard server, Fabric, Forge, or another Java-based implementation. Java whitelist entries are associated with a player name and UUID. The UUID that works depends on whether the server authenticates players online or calculates offline UUIDs.
#1 Best Overall
- Play and share with friends on console, mobile and Windows 10
- discover community creations in the new in-game store
- access new mini games and game modes through servers
Bedrock Dedicated Server
Use Bedrock instructions when the server is the official Bedrock Dedicated Server. Bedrock allowlist entries use a gamer tag and can include an XUID and the ignoresPlayerLimit field. Do not create a Java-style UUID entry in allowlist.json.
Fix a Java whitelist that is not working
1. Turn on the Java whitelist and understand enforce-whitelist
From the server console or an in-game operator account, run:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match/whitelist onThen check the active server.properties file for:
white-list=trueIf you edit server.properties directly, restart the server before judging the result. The live command is safer for a quick change because it updates the running server. A spelling difference between white-list and other panel labels can make a panel appear enabled while the Java process is still running with the list disabled.
enforce-whitelist is separate. It controls what happens to players who are already online when the list is reloaded; it does not enable the whitelist. Turning it on cannot fix a whitelist that is currently off.
2. Add and list players with the built-in commands
Use the running server to resolve the player rather than typing a UUID by hand:
/whitelist add PlayerName
/whitelist listReplace PlayerName with the exact Java account name. The list command confirms what the server process believes is present. If the name is absent, add it again while the player is using the account that will actually connect.
Removing and re-adding is useful after an authentication-mode change:
/whitelist remove PlayerName
/whitelist add PlayerNameDo this only after confirming the server is running in its intended mode, because the same name can map to a different UUID in online and offline mode.
3. Reload after editing whitelist.json
If you edited whitelist.json outside the game, run:
/whitelist reloadThe reload tells the running Java server to read the file again. Without it, the process can continue using the old in-memory list even though a text editor shows the new entry. Back up the file before manual edits and preserve valid JSON syntax. When possible, stop the server, make the change, start it, and use /whitelist list to verify the result.
4. Check online-mode and offline-mode identity
Java online-mode servers use authenticated identities. Offline-mode servers calculate an offline UUID from the player name. If a whitelist entry was created while the server was in one mode and the server later switched modes, the visible name may look correct while the stored UUID no longer matches the connecting account.
To recover, set the server to its intended mode, start it, remove the stale entry, add the player with /whitelist add PlayerName, and reload if you edited the file. Do not invent or paste a UUID from an unrelated lookup; let the running server resolve the account in its current mode.
5. Do not use an operator as a negative test
Java operators can connect without being present in whitelist.json. Therefore, an operator successfully joining does not prove that the whitelist is disabled. Test with a normal, non-operator account, or temporarily remove operator status from the test account:
/deop PlayerNameRestore the required permission after testing with:
/op PlayerNameUse a separate test account if you need to validate access repeatedly.
Rank #4
- Play and share with friends on console, mobile and Windows 10
- discover community creations in the new in-game store
- access new mini games and game modes through servers
6. Compare the server log with the actual identity
When a listed player is rejected, read the connection and authentication lines in the server log. Compare the name and identity reported there with the entry created by /whitelist add. This catches a misspelled name, a different account with a similar name, and an online/offline UUID mismatch. The log is more reliable than guessing from a saved JSON record.
Fix a Bedrock allowlist that is not working
1. Add the gamer tag with /allowlist add
Microsoft’s Bedrock Dedicated Server documentation identifies the command as the easiest way to add a player:
/allowlist add GamerTag
/allowlist listUse the player’s exact Bedrock gamer tag, including capitalization and spacing as the account presents it. Confirm the result with /allowlist list before testing a connection.
2. Reload after external edits
If you changed allowlist.json in a file manager, panel, or container, run:
/allowlist reloadMicrosoft states: “If you make modifications outside Minecraft, you’ll need to run the command /allowlist reload so the server reads the changes.” A restart also reads the file, but reload is the direct fix when the server is already running.
3. Validate the Bedrock entry fields
Bedrock’s official schema includes name, optional xuid, and ignoresPlayerLimit. Keep the JSON valid and use the gamer tag in the name field. Do not copy a Java UUID into this file. If your panel generates entries, compare its output with the file that the active Bedrock process is actually using.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
4. Check permissions and the account used for testing
Use a Bedrock account without elevated server permissions when testing whether an unapproved player is blocked. Panels and permission systems can apply their own access rules, so verify that the account reaching the server is the one you added and that a proxy or gateway is not handling the connection before the Bedrock process.
Why a whitelist entry can look correct but still fail
The wrong file or server directory is active
Servers can be launched from a different working directory than the one you opened in a file manager. This is common after moving a world, changing a startup script, restoring a backup, or running the server in a container. Use the console commands to see the running list, then locate the directory and file associated with that process. If the command output and the edited file disagree, you changed the wrong copy.
The server overwrites your edit on shutdown
Editing a live JSON file while the server is writing it can be undone when the process saves its in-memory state. Stop the server before a manual edit, keep a backup, start it, and verify with the list command. If the entry disappears after every restart, inspect file ownership and permissions, container volume mounts, and startup automation that restores a template.
A panel or script turns access control off
Some management panels expose a whitelist toggle separate from the text file. A startup script may also apply its own server.properties values. If /whitelist on works temporarily but the setting is off after a restart, inspect the launch configuration and panel-generated properties rather than repeatedly editing the JSON list.
A proxy or network layer applies a different list
If players connect through a proxy, verify access control at every layer. The backend Java or Bedrock list may be correct while the proxy, gateway, or panel has its own allowlist or forwarding configuration. Test a direct connection where your architecture permits it, and read logs from the layer that rejects the connection.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.What to do for each common symptom
Nobody is blocked
- Confirm the edition and run the matching list command.
- For Java, run
/whitelist onand verifywhite-list=true; for Bedrock, verify the server’s allowlist switch in its configuration or panel. - Check startup scripts and automation for a setting that disables access control.
- Test with a non-operator account and read the connection log.
One approved player is blocked
- Re-add the account using the built-in command.
- Check spelling, gamer tag, and the identity reported in the log.
- For Java, confirm online-mode or offline-mode has not changed since the entry was created.
- Reload after any file edit, then test again.
Unapproved players can join
- Verify the active switch, not merely the presence of a JSON file.
- Make sure the test account is not a Java operator.
- Check whether a proxy or panel is granting access before the game server evaluates its list.
- Restart after changing a property file and confirm the setting with a fresh connection.
Changes vanish after restart
- Identify the exact process and working directory used by the startup command.
- Check file ownership and write permissions for the server user.
- If using containers, verify that the host directory is mounted to the path the process reads.
- Inspect scripts, templates, scheduled restores, and panel settings that may replace the file.
- Stop the server before editing, start it, and confirm the list from the console.
A Bedrock entry is ignored
- Confirm that the server is Bedrock Dedicated Server, not Java.
- Use the exact gamer tag with
/allowlist add GamerTag. - Check the
name, optionalxuid, andignoresPlayerLimitfields for valid JSON. - Run
/allowlist reloadafter an external edit. - Review the Bedrock log and any proxy or panel rules.
Java and Bedrock differences at a glance
| Item | Java Edition | Bedrock Dedicated Server |
|---|---|---|
| Command family | /whitelist |
/allowlist |
| Primary list file | whitelist.json |
allowlist.json |
| Identity data | Player name and UUID; UUID behavior differs between online and offline mode | Gamer tag, with optional XUID and ignoresPlayerLimit |
| Add and inspect | /whitelist add PlayerName and /whitelist list |
/allowlist add GamerTag and /allowlist list |
| Reload after file edit | /whitelist reload |
/allowlist reload |
| Important test caveat | Operators can bypass the whitelist; use a non-operator test account | Test with the intended gamer tag and an account without elevated permissions; check any panel or proxy rules |
A clean recovery procedure
When several settings are uncertain, use this controlled sequence instead of changing multiple files at once.
- Record whether the server is Java or Bedrock and whether a proxy or panel sits in front of it.
- Back up the relevant list file and the active property file.
- Start the server in its intended configuration.
- Use the edition-specific add and list commands to create a known-good entry.
- Enable Java with
/whitelist on, or verify the Bedrock allowlist switch in the active configuration. - Test with one listed account and one unlisted, non-privileged account.
- If you edited a file, run the matching reload command.
- Restart only after the live behavior is correct, then repeat the two-account test.
- If the result changes after restart, investigate the active directory, permissions, volume mounts, and startup automation.
What the key settings actually control
- Java
white-list: the property that enables the Java whitelist when set to true. - Java
/whitelist on: enables the list in the running server. - Java
enforce-whitelist: governs removal of already-online players during a reload; it is not the enable switch. - Java
/whitelist reload: rereadswhitelist.jsonafter an external change. - Bedrock
/allowlist reload: rereadsallowlist.jsonafter an external change. - Operator or elevated permissions: can make a test account appear to bypass normal access checks, so use an ordinary account when validating rejection.
When to stop editing and read the logs
If the command list shows the correct account but the connection still fails, the next useful evidence is the server log. Look for the identity accepted during authentication, the reason for the rejection, and whether the request reached the game server or stopped at a proxy. A log identity that differs from the saved entry points to the account, spelling, gamer-tag, UUID-mode, or forwarding problem; a correct identity with no rejection usually points to a disabled switch or another access-control layer.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems
