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 matchiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Playing with friends? Godlike.Host runs hosted Minecraft Java servers from 10 data-center locations, with free DDoS protection.
The quickest reliable method is to read the server’s own files. In the server root, usercache.json maps names to UUIDs; for players who have data in a world, the filenames in world/playerdata are their UUIDs. whitelist.json and banned-players.json also store UUIDs beside names. Only use an online lookup when the player has never joined that server, and treat Mojang endpoint instructions as subject to change.
Which lookup method should you use?
Start with a local file whenever possible. It does not depend on an external service and reflects the UUID that your server is actually using.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Method | Player must have joined? | Works for an unseen player? | External endpoint | Best use |
|---|---|---|---|---|
usercache.json |
Yes, the name must be in the server cache | No | None | First check for a name-to-UUID mapping |
world/playerdata filenames |
Yes, the player must have world data | No | None | Confirm a UUID for someone who played on that world |
whitelist.json or banned-players.json |
Usually; an administrator may also have added the entry manually | Sometimes, if an entry already exists | None | Check the UUID currently used by an access or ban rule |
| Mojang profile lookup | No | Yes, if the service responds | Yes; the current endpoint’s status is uncertain | Find a Java account that has never joined your server |
| Third-party lookup site | No | Often | Yes | Convenience or name-history research; independently verify before changing server permissions |
Find the UUID in usercache.json
usercache.json is normally in the server’s root directory—the same directory that contains server.properties, the server JAR or startup script, and the world folder. It is a JSON array containing cached player records. The important fields are the player’s name and uuid; other fields may be present.
Locate the file
- Linux or macOS: open the directory from which you start the server, then run
lsand look forusercache.json. - Windows: open the folder used by the server’s startup shortcut or batch file. Do not search only inside
.minecraftunless that is also where this particular server runs. - For a managed host, use its file manager or SFTP and open the server’s top-level directory, not a client-side Minecraft folder.
Read a record
Open the file in a text editor and search for the exact in-game name. A matching object pairs that name with a UUID. Preserve the hyphens when you copy it. If the name is absent, this cache cannot answer the question; continue with the world files or an access-list file.
#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
Command-line examples
On a system with jq, this prints every cached name and UUID:
jq -r '.[] | [.name, .uuid] | @tsv' usercache.jsonTo search for one name (case-insensitive) on Linux or macOS:
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minutejq -r --arg n "PlayerName" '.[] | select(.name|ascii_downcase == ($n|ascii_downcase)) | [.name, .uuid] | @tsv' usercache.jsonOn Windows PowerShell, the equivalent is:
Get-Content .usercache.json | ConvertFrom-Json | Where-Object { $_.name -ieq "PlayerName" } | Select-Object name, uuidThe cache only covers names the server has recorded. Because the cache-entry retention period is unspecified, do not treat a missing or stale-looking entry as proof that an account has never existed.
Use world/playerdata when the player has played
Java Edition stores each player’s world data in a file named <uuid>.dat under the world’s playerdata directory. For the default world, the path is usually world/playerdata; a server can use a different world name, so inspect the world directory named in server.properties if the default path is absent.
- Stop or otherwise quiesce the server before making administrative file changes, and keep a backup of the directory you are inspecting.
- Open the relevant world’s
playerdatafolder. - Read the filename before
.dat. That 36-character dashed value is the UUID. - Match the UUID to a name using
usercache.json,whitelist.json, orbanned-players.jsonwhen you need to identify which player the file belongs to.
This method confirms that the UUID has world data in that particular world. A player may have joined the server but have no file in the world you checked, for example if the server uses multiple worlds or the player never entered that world.
Rank #2
- Learn your way around one block at atime in the new tutorial mode
- Craft all sorts of items from boats todiamond armor and create enormousstructures
- Team up with friends in eight-playeronline multiplayer and four-player splitscreen modes
Check the whitelist and ban files
whitelist.json
The whitelist is a JSON array. Each entry has two relevant fields: uuid and name. The UUID is the identifier used by the permission check; name is a human-readable label. If a player changed their name, the UUID is the stable value for an online-mode account, while the label may reflect the name that was recorded when the entry was created.
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 →[
{
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "PlayerName"
}
]banned-players.json
Ban entries likewise pair a UUID with a name, along with ban metadata. When resolving a ban or diagnosing an unexpected denial, trust the UUID field for the rule and use the name only to recognize the account.
Extract entries with commands
jq -r '.[] | [.name, .uuid] | @tsv' whitelist.json
jq -r '.[] | [.name, .uuid] | @tsv' banned-players.jsonIf you edit a whitelist entry manually, use the dashed 8-4-4-4-12 UUID form. A compact, undashed value copied from an API response will not match the expected format.
Find a UUID for a player who has never joined
Local files cannot contain a player that your server has never seen. A Mojang profile lookup is the intended external approach for an online-mode Java account, but endpoint instructions circulating in guides conflict and the current endpoint state is uncertain. Treat the following URLs as documented examples, not a guarantee that every request will work today:
- Single-name GET described by one guide: https://api.mojang.com/users/profiles/minecraft/<username>
- Bulk POST described by the same guide (up to 10 names): https://api.minecraftservices.com/minecraft/profile/lookup/bulk/byname
- A different usercache description lists a POST to https://api.mojang.com/profiles/minecraft
Because these references disagree, check Mojang’s current developer documentation or service response before building an automation around any one URL. Do not assume a successful HTTP request means the name is valid: inspect the returned object and handle a not-found response.
Rank #3
- ENGAGING AND COOPERATIVE: Experience the thrill of Minecraft in a unique and cooperative board game format. Perfect for teams of 2 to 4 players, the game encourages joint strategies and shared victories
- EVER-CHANGING GAMEPLAY: With a map that changes every time you play, this game offers high replay value, making every game a unique and unpredictable experience
- QUALITY COMPONENTS: The game includes 25 wooden blocks, 18 world tiles, 4 inventory boards, 6 player cards, 9 buildings, 12 mob tokens and more. All components are crafted with care to enhance your gaming experience
- AGE-APPROPRIATE CHALLENGE: Aimed at ages 7 and up, this game offers a great balance of fun and challenge, making it a great choice for family game nights, parties, or gatherings
- TRUSTED BRAND: With over 130 years of experience, Ravensburger ensures top quality games that stimulate the mind, engage the hands, and touch the heart
Convert the response to the server format
Mojang responses are commonly shown as a compact UUID without hyphens. Minecraft server files expect the dashed form:
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxInsert hyphens after characters 8, 12, 16, and 20. Do not change any hexadecimal characters or add braces. Before adding the value to a whitelist, compare it with the exact UUID formatting used by another known-good entry.
Understand online-mode and offline-mode UUIDs
Online-mode servers
In online mode, the server associates a player with the UUID supplied through account authentication. Name changes therefore do not normally require replacing a player’s UUID in server data. Existing local records remain the most useful authority for that server.
Offline-mode servers
Offline mode does not obtain an authenticated UUID from Mojang. The server derives a version 3 UUID from an MD5 hash of the string OfflinePlayer: followed by the exact username. The third UUID group begins with 3, which identifies the version.
Free tools Windows power users keep installed
One-click scans. No signup required.
A name change produces a different input string and therefore a different UUID. That is why a whitelist or player data may appear to “break” after a rename on an offline-mode server: the server is calculating a new identity, not finding the old one under a new label.
Rank #4
- Minecraft Dungeons Hero Edition includes the Hero Pass DLC content: a Hero Cape, two player skins, and a chicken pet. It also includes the Jungle Awakens and Creeping Winters DLC packs.
- Dungeon Creeper Battle new-and-nasty mobs in this all-new action-adventure, inspired by classic dungeon crawlers.
- Multiplayer Up to four players can team up and fight together in co-op mode.
- Power Up Unlock dozens of unique items and weapon enchantments for devastating special attacks.
- Options Personalize your character, then fight up-close and personal with melee swings, hang back with ranged attacks, or tank your way through swarms of mobs, by heavy armor
Reproduce an offline UUID
This Python example implements the same name-based calculation and prints the dashed value:
import hashlib
import uuid
name = "PlayerName"
digest = bytearray(hashlib.md5(("OfflinePlayer:" + name).encode("utf-8")).digest())
digest[6] = (digest[6] & 0x0f) | 0x30
digest[8] = (digest[8] & 0x3f) | 0x80
print(uuid.UUID(bytes=bytes(digest)))Use the exact capitalization the offline server receives. PlayerName and playername hash to different UUIDs.
Bedrock players connecting through Geyser or Floodgate
Bedrock clients can appear on a Java server through compatibility software such as Geyser and Floodgate. Reports describe these players’ UUIDs as beginning with 00000000-0000-0000-. Treat that prefix as a diagnostic clue rather than a universal rule: the bridge configuration determines how identities are represented.
For a Bedrock-connected player, inspect the same local files that you would inspect for a Java player. The UUID in usercache.json, an access-list entry, or the relevant playerdata filename is the value your server is actually using; do not substitute a UUID copied from a Java-only lookup.
Troubleshoot “whitelist UUID not working”
The UUID has no hyphens
Reformat the 32 hexadecimal characters into 8-4-4-4-12 groups. The compact form returned by many APIs is not the spelling expected in whitelist.json.
Best Value
- Official Minecraft Puzzle Game – Hands-On Logic Game Based on the Best-Selling Video Game.
- 40 Strategic Challenges – Use the Actions to Navigate & Solve Increasingly Tough Puzzles.
- No Screens, Just Strategy – Promotes Problem-Solving with Off-Screen Minecraft Fun.
- Perfect for Ages 8+ – Great Gift for Minecraft Fans Who Love a Challenge!
- Trusted by Parents Worldwide – With Over 50 Million Sold, ThinkFun is the World's Leading Manufacturer of Brain Games and Mind-Challenging Puzzles!
The UUID belongs to a different identity mode
Compare the server’s mode with the source of your UUID. An online-mode UUID, an offline-mode hash, and a Bedrock bridge UUID are not interchangeable. Generate or retrieve the value using the same mode and connection path the player uses.
The player renamed themselves on an offline server
Calculate the offline UUID from the new exact username, then decide whether to migrate the old player data and whitelist entry. Copying the old name beside the new hash does not make the two identities equivalent.
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 →The name is absent from usercache.json
Check the correct server root and every relevant world’s playerdata directory. If no local record exists and the player has never joined, use a Mojang lookup only after confirming the current API documentation.
The file shows a familiar name but an unexpected UUID
Use the UUID as the authoritative key and the name as a label. Verify it against a second local source—such as the playerdata filename and whitelist entry—before changing permissions.
Quick Recap
A repeatable administrator workflow
- Identify whether the server is online mode, offline mode, or accepting Bedrock connections through a bridge.
- Search
usercache.jsonin the server root. - If the player has played, inspect each applicable
world/playerdata/<uuid>.datfilename. - Check
whitelist.jsonandbanned-players.jsonfor an existing mapping. - For an unseen online-mode player, consult Mojang’s current API documentation and validate the response.
- Convert any compact UUID to the dashed
8-4-4-4-12form before placing it in a server JSON file. - For offline mode, calculate the version 3 hash from the exact username; for Bedrock connections, prefer the UUID recorded by the bridge-enabled server.
- After any edit, reload the relevant list using the server’s normal administrative command or restart procedure, then test with the affected account.
What not to rely on
- Do not infer a UUID from a player’s current name on an offline-mode server; the hash is case-sensitive and name changes create new identities.
- Do not paste an undashed API value directly into
whitelist.json. - Do not treat a third-party lookup as authoritative when a local server record exists. Sites such as NameMC or MinecraftUUID.com can be convenient for name history, but their accuracy is not guaranteed.
- Do not assume a UUID prefix alone proves how a player connected; confirm the value in the server’s own files.
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.
