Minecraft UUID Lookup

What is a Minecraft UUID?

This Minecraft UUID lookup turns usernames into the UUIDs that Java Edition servers use to identify players. Paste up to 100 names above, one per line, and the tool asks the Mojang API for each account. You get a table with a copy button per player and a CSV of every name and UUID that was found.

A UUID (universally unique identifier) is a 128-bit number, written as 32 hexadecimal characters in five groups: 069a79f4-44e9-4726-a5be-fca90e38aaf5. Every Java Edition account gets one when it is created, and it never changes. That is the point of it. A player can change their username, but their UUID stays the same, so a server that stores data by UUID keeps their inventory, permissions and bans after a rename.

Servers store almost everything about a player under the UUID, not the name:

• whitelist.json, ops.json and banned-players.json list each player as a UUID plus the last name the server saw
• world/playerdata/<uuid>.dat holds the inventory, position, health and ender chest
• world/stats/<uuid>.json and world/advancements/<uuid>.json hold statistics and advancements
• usercache.json maps recent names to UUIDs so the server does not ask Mojang every time
• Plugins such as LuckPerms, EssentialsX and most economy plugins key their data by UUID too

Most commands still accept names, because the server looks the name up for you. You need the UUID itself when you edit those files by hand, move player data between servers, write a plugin config that asks for UUIDs, or check whether two accounts are the same player.

Ask the AI assistant

The AI assistant under the lookup answers questions about UUIDs: why a player's UUID differs on an offline-mode server, which UUID a whitelist needs, or what to do when a name isn't found. It's free, with 20 questions a day.

How the lookup works

Mojang has a bulk endpoint, POST https://api.mojang.com/profiles/minecraft, that takes a JSON array of up to 10 usernames and returns the id and the current name of each account it finds. Names that do not belong to an account are left out of the answer.

A browser cannot call that endpoint directly, because Mojang does not send the CORS headers that let a web page read the response. So this tool sends your list to a small proxy on chunkpod.com, which splits it into batches of 10, calls Mojang one batch at a time and returns the results. Nothing is stored. The proxy only accepts valid Java Edition names and at most 100 per request.

Mojang returns ids without dashes (069a79f444e94726a5befca90e38aaf5). Minecraft's own files use the dashed form, so the tool adds the dashes in the usual 8-4-4-4-12 layout. If a plugin asks for the undashed form, remove the four dashes.

The lookup is case-insensitive. notch, NOTCH and Notch all return the same account, and the table shows the name with the capitalization the account really uses.

Online-mode and offline-mode UUIDs

The UUID a player gets on your server depends on the online-mode setting in server.properties. This is the source of most UUID confusion, so it is worth knowing how both kinds are made.

Online mode

With online-mode=true, the default, the server checks every joining player with Mojang's session servers. The player has to own the game, and the server uses the UUID of their Microsoft account. That is the UUID this tool looks up. It is the same on every online-mode server, so a player who joins your server and someone else's has the same UUID on both.

Online-mode UUIDs are random, version 4 UUIDs. You can spot them by the first character of the third group, which is always 4. In 069a79f4-44e9-4726-a5be-fca90e38aaf5 the third group is 4726.

Offline mode

With online-mode=false, the server does not check anything with Mojang. It trusts whatever name the client sends and makes a UUID from that name. The server takes the text OfflinePlayer: plus the username, hashes it with MD5, and turns the hash into a version 3 UUID. For Notch that gives b50ad385-829d-3141-a216-7e7d7539ba7f. The third group starts with 3.

Because the offline UUID is built from the name alone:

• It is not the player's real UUID, and the Mojang API cannot return it. This tool only returns online-mode UUIDs
• It changes when the name changes, even by capitalization. Steve and steve get different offline UUIDs, so their inventories are separate
• Anyone who types the same name gets the same UUID, and with it that player's inventory, op status and permissions

That last point is why offline mode is dangerous on a public server. Anyone can log in as your admin by typing the admin's name. Offline mode only makes sense on a backend server behind a proxy that does the authentication, which the next section covers, or on a LAN with people you trust.

Why your whitelist or plugin data stops working

A mismatch between the two kinds is the usual cause of "my whitelist does not work" or "everyone lost their items". Some common cases:

• You looked up UUIDs with a tool like this one, but the server runs in offline mode. The server compares the offline UUID of each joining player with the online UUIDs in whitelist.json, and nobody matches
• You switched a server from offline to online mode (or back). Every player gets a new UUID, and the server treats them as new players with empty inventories. Their old data is still in world/playerdata/, under the old UUID
• A plugin was set up on a server with one mode, and its database moved to a server with the other

Fixing a switch between modes means renaming each world/playerdata/<old-uuid>.dat file (and the stats and advancements files) to the new UUID, or using a migration plugin. Look up the new online UUIDs here, and work out the old offline ones from the names. Back up the world first.

UUIDs behind a proxy

On a network with Velocity or BungeeCord, the proxy handles logins. The proxy runs in online mode, and the backend servers run with online-mode=false, because they cannot check the session servers themselves: the player has already been authenticated by the proxy.

The problem is that an offline backend would make offline UUIDs for everyone. To avoid that, the proxy forwards the real UUID (and the player's IP address and skin) to the backend:

• Velocity uses modern forwarding. Set player-info-forwarding-mode = "modern" in velocity.toml and enable Velocity support in each Paper server's paper-global.yml with the same secret. The Velocity config builder and the Paper config generator write both sides
• BungeeCord and Waterfall use legacy forwarding. Set ip_forward: true in the proxy's config.yml and settings.bungeecord: true in each backend's spigot.yml. The BungeeCord config generator and the spigot.yml generator cover those lines

If forwarding is off or set up on only one side, the backend falls back to offline UUIDs, and you get the same lost-data problems described above. A quick check: run /lp user <name> info with LuckPerms, or look at the newest file in world/playerdata/, and compare the UUID with the one this tool returns. If they differ, forwarding is not working.

Bedrock players and Floodgate

Bedrock Edition accounts are Xbox accounts, not Java accounts, so the Mojang API does not know them and this tool cannot look them up. If you let Bedrock players join a Java server with Geyser and Floodgate, Floodgate makes a UUID for each of them from their Xbox user ID. Those UUIDs start with a run of zeros, for example 00000000-0000-0000-0009-01f6b7c2a1d3. Floodgate also puts a prefix (by default .) in front of Bedrock names so they cannot clash with Java names. Use Floodgate's own commands or its linking feature to find those UUIDs.

Why a name is not found

The tool lists every name that did not match an account under "Not found". The usual reasons:

• Typo or wrong spelling. Check underscores and digits. Letters are not case-sensitive, but l and I or 0 and O are different characters
• The player changed their name. Java Edition players can change their name every 30 days. Once they do, their old name no longer finds them, and after the name is released someone else can take it. Mojang removed the name history API in 2022, so there is no official way to look up an old name. If the player joined your server before, usercache.json still has the old name next to their UUID
• The account is a Bedrock account. See the section above
• The name was never taken, or the account was deleted.

Names that cannot be Java Edition names at all, such as ones with spaces, dashes or more than 16 characters, are skipped before the lookup and shown under the text box. Current rules allow 3 to 16 letters, digits and underscores. A few very old accounts have shorter names, so the tool accepts those too.

Looking up UUIDs yourself

You can call the same Mojang endpoints from a terminal or a script, where CORS does not apply.

One name:

curl https://api.mojang.com/users/profiles/minecraft/Notch

Several names at once (at most 10 per call):

curl -X POST https://api.mojang.com/profiles/minecraft \
  -H "Content-Type: application/json" \
  -d '["Notch", "jeb_"]'

The other way round, from a UUID to the current name and skin:

curl https://sessionserver.mojang.com/session/minecraft/profile/069a79f444e94726a5befca90e38aaf5

Mojang rate-limits these endpoints per IP address. A few hundred lookups in a short time can get a 429 Too Many Requests answer, and you have to wait before trying again. The tool shows the same message when Mojang rate-limits the proxy. For large lists, split them and look them up a few minutes apart.

Common mistakes

• Using online UUIDs on an offline server. Check online-mode in server.properties first. The server.properties generator explains the setting and what else changes with it
• Editing whitelist.json or ops.json while the server runs. The server keeps its own copy in memory and writes it back, which can undo your change. Stop the server first, or use /whitelist add and /op in the console, which look up the UUID for you
• Dropping the dashes in Minecraft files. whitelist.json, ops.json and player data file names use the dashed form. Only some plugin configs and web APIs want the undashed one
• Matching players by name in your own scripts or databases. Names change and can be reused by other accounts. Store the UUID, and treat the name as a label that may be out of date
• Forgetting forwarding on one backend. On a proxy network, a single backend without forwarding gives its players offline UUIDs and separate data from the rest of the network

Related tools and guides

UUIDs are one part of managing players. The whitelist generator and the ops.json generator run the same lookup and write whitelist.json and ops.json for you. The server.properties generator sets online-mode and white-list, the Velocity config builder and the BungeeCord config generator set up forwarding so backends see real UUIDs, and the spigot.yml generator has the bungeecord switch for Spigot and Paper backends.

For permissions that follow a player through name changes, the LuckPerms setup guide shows how LuckPerms stores users by UUID. The EssentialsX setup guide covers the player data EssentialsX keeps per UUID, such as homes and balances, and the optimal server.properties settings post covers online-mode alongside the other settings worth changing on a new server.