For a Java Edition server, check the server root’s usercache.json first, then inspect world/playerdata filenames or an existing whitelist.json/banned-players.json. Those local files provide the UUID without an online lookup. Players who have never joined require a Mojang profile lookup, whose current endpoint and method should be verified before you automate against it.
Playing with friends? Godlike.Host runs hosted Minecraft Java servers from 10 data-center locations, with free DDoS protection.
Choose the source that matches your situation
A UUID lookup is easiest when you know whether the player has already connected and whether the server runs online or offline mode. Use the server’s own data whenever possible: it reflects the identity that server actually stored.
As an Amazon Associate I earn from qualifying purchases.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →| Source | Player must have joined? | Works for an unseen player? | Third-party or API dependency | Best use |
|---|---|---|---|---|
usercache.json |
Yes | No | None | First check for a Java player who has connected |
world/playerdata/<uuid>.dat |
Yes, on that world | No | None | Confirming identities from saved player data |
whitelist.json or banned-players.json |
Usually; the entry must already exist | No | None | Finding the UUID already used by an access or ban entry |
| Mojang profile lookup | No | Yes | Depends on a current Mojang endpoint | Players who have never joined your server |
| Third-party lookup site | No, in many cases | Often | Yes; accuracy is not established | Convenience or name-history research, not authoritative server administration |
Find the UUID in usercache.json
Locate the file
usercache.json is in the server’s root directory: the directory containing the server JAR and files such as server.properties, eula.txt and the world folder. It is not normally inside world/playerdata. Stop the server, or at least avoid editing while it is running, so you read a consistent file and do not overwrite changes on shutdown.
Open the file with a text editor that can handle JSON. Search for the player’s current or former in-game name. Each matching record maps a name to a UUID; copy the value associated with that name exactly. The cache is populated for players who have joined, so a name that has never connected will not be present. The file’s retention period is not established, so do not treat the file as a guaranteed historical record for every past player.
#1 Best Overall
Search from a terminal
On Linux or macOS, print the matching lines with:
grep -i 'PlayerName' usercache.jsonOn Windows PowerShell, use:
Select-String -Path .usercache.json -Pattern 'PlayerName'Replace PlayerName with the exact name you are checking. These commands locate text; they do not validate that a copied value is the right UUID. If a player has changed names, inspect every matching record and verify which name the server currently uses in its access list.
Read a UUID from the world’s player-data filenames
Java Edition stores per-player data as files named <uuid>.dat under the world’s playerdata directory. For a default world, the path is:
world/playerdata/Every filename ending in .dat contains the UUID used for that saved player. This method is reliable for anyone who has played on that particular world, even if the cache entry is difficult to find.
When the folder is not named world
Servers can use a custom world directory. Check the level-name value in server.properties; that value identifies the primary world folder. Then open its playerdata subfolder. A multiworld plugin may maintain additional worlds, so check the world in which the player actually played.
What this method can and cannot tell you
- The filename gives the UUID, but the file itself does not provide a convenient human-readable name.
- An absent file means only that no player-data file was found in that world; it does not prove the person has never connected to another world or server.
- Do not rename a
.datfile casually. The filename is part of the server’s identity mapping, and changing it can make the saved data appear to belong to another UUID.
Check whitelist.json and banned-players.json
Access and ban lists are UUID-keyed. In whitelist.json, each entry has two fields: uuid and name. The name is a label for administrators; the UUID is the identity the server matches. banned-players.json likewise records a UUID alongside a name and ban metadata.
Read an existing entry
- Stop the server or make a backup copy of the file before editing.
- Open
whitelist.jsonorbanned-players.jsonin a JSON-aware editor. - Search for the player’s name and copy the corresponding
uuidvalue. - Keep the UUID’s hyphens and letter casing as stored unless you have a specific reason to normalize them.
If the player is already whitelisted, the server has already resolved a UUID for that entry. Treat that local value as more relevant to this server than a result copied from an unrelated lookup site.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Understand the UUID format before fixing a whitelist error
Dashed versus undashed values
whitelist.json expects the conventional dashed form: 8-4-4-4-12 hexadecimal characters, for example xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Some Mojang API responses are returned as a 32-character value with the hyphens removed. If you transfer such a response into a whitelist entry, insert hyphens after characters 8, 12, 16 and 20.
Do not add braces, quotation marks inside the value, spaces or a prefix such as UUID:. The JSON property itself still needs quotes, as in:
Rank #3
- The classic UNO card game builds fun on game night with a Minecraft theme.
- UNO Minecraft features a deck and storage tin decorated with graphics from the popular video game.
- Players match colors and numbers to the card on top of the discard pile as in the classic game.
- The Creeper card unique to this deck forces other players to draw 3 cards.
- Makes a great gift for kid, teen, adult and family game nights with 2 to 10 players ages 7 years and older, especially Minecraft and video game fans.
{
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "PlayerName"
}Why “whitelist UUID not working” happens
- The value was copied without converting an undashed API response to the dashed format.
- A UUID from a different account, similarly named player or old offline-mode identity was used.
- The JSON syntax was broken by a missing quote, comma or bracket.
- The file was edited while the server was running and the server later rewrote it.
- The player is connecting through Geyser/Floodgate and therefore does not use the Java UUID you expected.
After editing, run the server’s normal whitelist reload command or restart it according to your administration practice. If the player is online, remove and re-add the entry only after confirming the UUID; repeatedly replacing entries with guesses can create duplicate or stale records.
Looking up a player who has never joined
A local cache and world save cannot contain an unseen player. Mojang profile lookups are the appropriate category of solution, but the endpoint details in commonly circulated guides conflict and no current verification against Mojang developer documentation is available.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Conflicting endpoint reports
One guide reports a GET request shaped like https://api.mojang.com/users/profiles/minecraft/<username>. The same material describes a bulk POST request, limited to 10 names, at https://api.minecraftservices.com/minecraft/profile/lookup/bulk/byname. A Minecraft Wiki description of the cache instead gives a POST to https://api.mojang.com/profiles/minecraft. Because these reports disagree, do not build a production script around one URL without checking Mojang’s current documentation and response format first.
Validate the result before using it
- Confirm that the returned name is the account you intended, not merely a similar spelling.
- Check whether the response uses a 32-character undashed UUID and convert it to the dashed form required by your JSON file.
- Keep a copy of the original access-list file before replacing an entry.
- If the account has never connected to your server, test the resulting whitelist entry with the player rather than assuming a successful HTTP response proves server compatibility.
Third-party services such as NameMC and MinecraftUUID.com can be convenient for name history, but their accuracy is not established. Use them as an optional cross-check, never as a substitute for the UUID already recorded by your own server.
Rank #4
- Now Minecraft lovers can play a special version of UNO!
- Same as Basic UNO but features Minecraft characters and includes special Creeper rule card. Draw this card and the other players have to draw three more cards from the pile!
- The goal is to get rid of all the cards in your hand.
- First player or team to 500 wins.
- When you're down to one card, don't forget to yell "UNO"!
Offline-mode UUIDs
An offline-mode server does not authenticate players through Mojang. Instead, the server derives a version 3 UUID from an MD5 hash of the literal prefix OfflinePlayer: followed by the username. Version 3 is visible in the UUID’s third group: it begins with 3.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Calculate the value locally
This Python example reproduces the derivation for a supplied username:
import hashlib
import uuid
name = "PlayerName"
raw = hashlib.md5(("OfflinePlayer:" + name).encode("utf-8")).digest()
offline_uuid = uuid.UUID(bytes=raw, version=3)
print(offline_uuid)The printed value is the dashed UUID to compare with your server files. The calculation is deterministic for the exact username string, but it is not a Mojang account identity.
The rename consequence
Because the username is part of the hash, changing a player’s name on an offline-mode server changes the derived UUID. Their old inventory, permissions or whitelist entry can therefore appear to vanish under the new name. Before migrating a name, record the old UUID and plan an explicit data or permission migration; do not assume online-mode name-change behavior applies.
Bedrock players using Geyser/Floodgate
A Bedrock player connecting through Geyser/Floodgate may not have the Java-style UUID you expect. The reported pattern for these connections starts with 00000000-0000-0000-. If a Bedrock user cannot join despite a UUID copied from a Java account lookup, inspect the UUID in your server’s own cache and access-list files for that connection type.
Recommended Free Tools
Do not overwrite a stored Geyser/Floodgate UUID with an online Java UUID merely because the names match. The bridge’s identity mapping is the value your server checks. For a mixed Java/Bedrock server, document which form belongs to each account before changing whitelist or ban files.
A repeatable administrator workflow
- Identify the edition and connection path. Confirm Java Edition, offline mode versus online mode, and whether the player is arriving through Geyser/Floodgate.
- Search the server root. Look up the name in
usercache.json. - Inspect saved worlds. Check the relevant world’s
playerdatafilenames and confirm the configuredlevel-nameif the folder is notworld. - Read existing access lists. Compare the name and UUID in
whitelist.jsonorbanned-players.json. - Use an online lookup only for an unseen player. Verify the current Mojang endpoint before sending requests, and convert the response to dashed form when required.
- Check the UUID family. A version 3 value points to offline-mode derivation; a
00000000-0000-0000-prefix indicates the reported Geyser/Floodgate pattern. - Back up, edit, reload and test. Preserve the original JSON, make one change, reload the whitelist or restart, and have the affected player test from the same connection type they normally use.
Common failure cases and fixes
The player is missing from usercache.json
They may never have joined this server, the cache may no longer contain the record, or the name may be misspelled. Check playerdata and access lists next. If all local sources are empty, use a verified Mojang lookup for an online-mode account.
The UUID works for one account but not another with the same name
Names are labels, not the key. Compare the complete UUID, the edition and the connection path. Offline-mode and Geyser/Floodgate identities can differ from an online Java profile even when the displayed name is identical.
The JSON file keeps reverting
The server may still be running and writing its in-memory list back to disk. Stop it before manual edits, retain a backup, then start or reload and inspect the file again.
Free tools Windows power users keep installed
One-click scans. No signup required.
A copied API value is rejected
Check for missing hyphens, an incorrect account, a stale endpoint response or an identity mismatch caused by offline mode or a Bedrock bridge. Compare the value with the server’s own files whenever the player has connected.
The Bottom Line
For an established Java player, the server’s own usercache.json, playerdata filename or access-list entry is the authoritative place to start. Only fall back to an online lookup for unseen players, and always account for dashed formatting, offline-mode hashing and Geyser/Floodgate identities.
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.
