A Minecraft whitelist fails for a small number of repeatable reasons: the wrong edition command was used, the list is not enabled, a manually edited file was never reloaded, a server-property change was never restarted, the player identity changed with online-mode, or an operator account is bypassing the test. Identify whether the server is Java Edition or Bedrock Dedicated Server first, then follow the matching command and file procedures below.
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.
Start by identifying the edition and server software
Java Edition dedicated servers and Bedrock Dedicated Server do not share whitelist commands, file names, or identity fields. A command that works on Java will not repair a Bedrock allowlist, and a Bedrock file edit will not affect a Java server. Check the server startup output, the server software download, or the hosting panel’s software selector before changing anything.
As an Amazon Associate I earn from qualifying purchases.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →| Item | Java Edition dedicated server | Bedrock Dedicated Server |
|---|---|---|
| Command family | /whitelist |
/allowlist |
| List file | whitelist.json |
allowlist.json |
| Add a player | /whitelist add PlayerName |
/allowlist add GamerTag |
| Show entries | /whitelist list |
/allowlist list |
| Reload after an external edit | /whitelist reload |
/allowlist reload |
| Identity data | Player name and UUID resolved by the server | Gamer tag, with optional XUID and ignoresPlayerLimit |
| Important bypass to check | Operators can connect without being listed | Check the server’s permission system and any proxy or panel rules |
Use the built-in command to create entries whenever possible. It lets the running server resolve the correct identity for its current authentication mode and avoids malformed JSON or an incorrect UUID.
Java: verify that the whitelist is actually enabled
Check the live setting
From the server console, or in chat as an operator, run /whitelist. On supported Java server versions this reports the current state and available subcommands. Run /whitelist on to enable the list, then run /whitelist list to see the entries the live server has loaded.
#1 Best Overall
The setting in server.properties is white-list=true. The property name contains a hyphen and uses the singular word list; do not substitute the Bedrock term allowlist. If the file says white-list=false, unapproved accounts can join because the access check is disabled. A hosting panel, startup script, or automation job can also rewrite this value, so check those controls if it keeps changing.
Do not confuse enforce-whitelist with the enable switch
enforce-whitelist controls what happens to players who are already online when the list is reloaded. When enforcement is enabled, players who are no longer allowed can be removed during that reload. It does not turn the whitelist on and it does not add anyone to the list. The access switch remains the live whitelist state, normally represented by white-list=true in the properties file.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Add and inspect the player through commands
- Run
/whitelist add PlayerName, replacingPlayerNamewith the exact Java account name. - Run
/whitelist listand confirm the name appears in the server’s response. - Ask the player to disconnect completely and reconnect. A player rejected before the add command may need a fresh connection attempt after the list has been updated.
- If the name is wrong, run
/whitelist remove OldName, then add the corrected name. Avoid editing a guessed UUID into the file.
Console commands are commonly entered without the leading slash by some panels, while in-game commands use the slash. Follow the input convention shown by your panel; the command itself is still the Java whitelist command family.
Java: reload manual edits and restart property changes
Reload whitelist.json after editing it
If you changed whitelist.json in a file manager, FTP client, container volume, or text editor, the running server may still be using its previous in-memory list. Save a valid file in the active server directory and run /whitelist reload. Java server documentation requires this reload after manual changes. Confirm the result with /whitelist list.
Stop the server before making a structural edit if your panel warns that live writes are unsafe. Keep a backup of the original file, preserve its JSON syntax, and make sure the file is owned and readable by the account that runs the server. A malformed file can prevent the list from loading or cause the server to replace it on startup.
Restart after changing server.properties
Changes to white-list and enforce-whitelist in server.properties generally take effect on restart. Stop the server cleanly, save the property, and start it again. If you can use the live whitelist command instead, do so for the immediate state, but still correct the property file so the next restart does not undo your setting.
Recommended Free Tools
Java identity problems: online mode, offline mode, and operators
Re-create entries after changing authentication mode
Java online-mode servers use authenticated account identities. Offline-mode servers calculate offline UUIDs from player names. Consequently, a whitelist entry created while the server was in one mode can fail after the mode changes, even when the visible name is identical.
- Check the current
online-modevalue inserver.propertiesand the startup configuration that may override it. - With the server running in its real production mode, remove the stale entry with
/whitelist remove PlayerName. - Add the account again using
/whitelist add PlayerName. - Run
/whitelist list, then test a new connection.
Do not copy a UUID from an unrelated mode or invent one by hand. The server command is the reliable way to resolve the identity it will check.
Make sure the negative test is not an operator
Java operators can connect without appearing in whitelist.json. An operator is therefore not a valid test for whether unlisted users are blocked. Test with a non-operator account, or temporarily remove operator status with /deop PlayerName, perform the test, and restore it with /op PlayerName only after the whitelist behavior is confirmed.
Bedrock: use the allowlist commands and schema
Add the exact gamer tag
Bedrock Dedicated Server calls the feature an allowlist. Use /allowlist add GamerTag and then /allowlist list. Microsoft’s Bedrock documentation identifies this command as the easiest way to add a player. Match the gamer tag exactly, including capitalization and spaces as the Bedrock account presents them.
Reload allowlist.json after external edits
For a direct file edit, save allowlist.json in the active Bedrock server directory and run /allowlist reload. Microsoft states that modifications made outside Minecraft require this command so the server reads the changes. A restart also reads the file, but reload is faster and makes the test explicit.
Check the Bedrock entry fields
Bedrock’s documented schema includes a required name value and may include an xuid value. It also supports ignoresPlayerLimit, which affects the player-limit check; it is not a replacement for adding the account to the allowlist. If an entry is ignored, compare the gamer tag with the value generated by /allowlist add, remove the hand-written entry, add the player through the command, and reload.
Do not place Java UUID objects into allowlist.json, and do not rename the file to whitelist.json. Bedrock will not interpret a Java list file as its own allowlist.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Why an approved player still cannot join
One player is blocked while others work
- Run the edition-specific add command again using the exact account name or gamer tag.
- Use the matching list command to verify that the running server, not merely a file browser, sees the entry.
- Check whether the server recently changed online-mode, offline-mode, authentication, or account ownership.
- Reload after a file edit and have the player make a completely new connection attempt.
- Read the rejection line in the server log and compare its identity spelling with the entry.
A successful add response followed by a missing entry in the list usually means you edited the wrong server directory, a panel restored an older file, or the process cannot write the directory.
Nobody is blocked
Confirm the active switch first: Java must have the whitelist enabled, while Bedrock must be using its allowlist feature and the expected server configuration. Then inspect startup scripts, scheduled jobs, panel settings, and proxy configuration for a command that disables or replaces the list. Test with a non-operator account on Java.
Unapproved players can join
On Java, check the live whitelist state and white-list=true, then ensure the test account is not an operator. If the connection passes through a proxy, verify that the proxy is enforcing the list on the backend players actually reach; a list on an unused backend directory cannot protect the public endpoint. On Bedrock, confirm that the server is the Bedrock Dedicated Server instance handling the connection and that no panel or automation has disabled the allowlist.
Players online before a reload remain connected
Review enforce-whitelist on Java. That setting determines whether players already online are removed when the list is reloaded. It does not affect the list’s ability to reject new connections, and changing it cannot repair a missing or incorrectly named entry.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsFind the active directory and persistence problem
Whitelist changes that disappear after a restart are usually written to a different directory or overwritten during startup. Use the path printed by the server process and compare it with the path opened in your panel or file manager.
- Check the process working directory and the panel’s configured server directory.
- Inspect container volume mounts; editing a host-side file that is not mounted into the running container changes nothing.
- Verify file ownership and permissions allow the server account to read and write the list.
- Look for startup scripts that copy a template
whitelist.jsonorallowlist.jsonover the live file. - Check whether a synchronization, backup, or deployment task restores an older version at launch.
- After starting, use the list command and a harmless add/remove test to prove which file the process is writing.
Make one change at a time, record the command response, and restart only after the live state is correct. This separates a command problem from a persistence problem.
Use the log to verify the identity the server rejects
When a player is denied, copy the relevant connection and disconnect lines from the server log. Compare the reported account name, gamer tag, UUID or XUID, and the reason for rejection with the entry generated by the server command. The log can reveal a misspelling, a different account than the player expected, a proxy forwarding a different identity, or a mode mismatch.
Do not infer an identity from a nickname, launcher profile, or an old backup. Remove and re-add through the command while the server is running in its actual mode, then reload if you changed a file. If the log shows the connection never reaches the server, troubleshoot the proxy or network path separately; a whitelist cannot reject a session that is being handled by another process.
A complete repair runbook
- Identify the edition. Decide Java dedicated server or Bedrock Dedicated Server. Select only that edition’s commands and file name.
- Check the live list. Run
/whitelist liston Java or/allowlist liston Bedrock. - Check the active switch. On Java, enable the whitelist with
/whitelist onand verifywhite-list=true. On Bedrock, confirm the allowlist is enabled in the server’s current configuration. - Re-add the account. Use
/whitelist add PlayerNameor/allowlist add GamerTagrather than typing an identity into a file. - Reload external edits. Run the matching reload command if you touched
whitelist.jsonorallowlist.json. - Restart property changes. Stop and start the server after editing
server.propertiesor another startup configuration. - Validate identity mode. If Java online-mode changed, remove and re-add the player in the current mode.
- Use a valid test account. On Java, test with a non-operator. On either edition, use an account that is not already connected through a privileged proxy or panel rule.
- Read the log. Compare the rejected identity and the server’s reason with the live list.
- Prove persistence. Restart, run the list command again, and confirm the entry remains in the directory used by the running process.
Prevent future whitelist failures
- Document whether each server is Java or Bedrock and keep edition-specific procedures beside its backup.
- Prefer add, remove, list, and reload commands over manual JSON edits.
- Back up the list before changing it and retain the server’s active directory path.
- Record online-mode changes and re-create Java entries after every authentication-mode change.
- Keep at least one non-operator test account for access-control checks.
- After panel, container, proxy, or startup-script changes, verify the list survives a clean restart.
- Review the target Minecraft version and server software after upgrades because command behavior, panels, and proxy integrations can change.
What the error usually means
| Symptom | Most likely cause | First corrective action |
|---|---|---|
| An approved player is rejected immediately | Wrong name or gamer tag, stale identity after mode change, or list not reloaded | Re-add with the live command, reload, and inspect the log |
| Everyone can join | Whitelist/allowlist disabled, operator test, or proxy bypass | Check the active switch and test with a non-operator account |
| Manual changes have no effect | Wrong file, wrong directory, or missing reload | Use the matching reload command and verify with the list command |
| Changes vanish after restart | Startup overwrite, wrong mount, or permissions | Trace the active directory, volume mount, and startup configuration |
| Bedrock entry is ignored | Java file/schema used, gamer-tag mismatch, or allowlist not reloaded | Use /allowlist add GamerTag, then /allowlist reload |
| Removing a player does not disconnect them | Java enforcement for already-online players is disabled | Review enforce-whitelist and reload the list |
The edition determines every command and file name. A list-file edit needs a reload, while a server-property edit may need a restart; separating those two operations resolves most reports that a whitelist is not working.
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.
