DEUF Mod Guide: Fixing Duplicate Entity UUIDs in Minecraft
DEUF (Duplicate Entity UUID Fix) is a lightweight server-side utility that automatically resolves duplicate entity UUID conflicts in your Minecraft world. If your server logs are flooded with 'Keeping entity that already exists with UUID' warnings, this mod silently fixes the root cause by assigning new unique IDs to conflicting entities.
Overview
DEUF is a zero-configuration server utility mod that solves a long-standing Minecraft bug: duplicate entity UUIDs. When entities in your world end up sharing the same UUID (common in older or heavily modified worlds), Minecraft floods your server console with "Keeping entity that already exists with UUID" warnings. These warnings can appear hundreds or thousands of times during chunk loading, cluttering logs and making it harder to spot real issues.
The mod works by intercepting chunk load events and scanning every non-player entity in the chunk. If it detects that an entity's UUID is already in use by another entity in the world, it generates a new random UUID and reassigns it. The fix is permanent: once an entity receives a new UUID, it saves with that UUID, so the conflict never reappears for that entity on subsequent loads.
DEUF is entirely server-side. Clients do not need to install it to join your server, making it ideal for dedicated servers where you can't control what mods players have installed. The mod adds no items, blocks, or gameplay changes whatsoever. It simply fixes a bug and cleans up your logs.
Getting Started
- 1
Install the mod
Drop the DEUF JAR file into your server's mods folder (or your single-player mods folder). No other mods are required. If you're running a dedicated server, only the server needs the mod installed.
- 2
Back up your world
Before starting the server with DEUF for the first time, back up your world. The mod modifies entity data by changing UUIDs, and while the changes are safe, it's always wise to have a backup before any mod touches saved entity data.
- 3
Start the server and explore
Launch the server and load into your world. On this first load, you'll actually see more log messages than before. In addition to the usual duplicate UUID warnings, DEUF adds its own INFO-level messages showing each UUID it reassigns (e.g., "Changing UUID of entity minecraft:painting that already existed from X to Y"). This is expected and only happens once per conflicting entity.
- 4
Explore affected areas
Walk through areas of your world that previously generated heavy log spam. The mod fixes entities as their chunks load, so you need to visit (or have the server load) the affected chunks at least once. After entities are fixed, their new UUIDs are saved to disk.
- 5
Enjoy clean logs on subsequent loads
After the first pass through your world, restart the server. The UUID warnings for all fixed entities will be gone. Any chunks you haven't visited yet will get fixed when they're loaded for the first time. Eventually, all duplicate UUIDs in your world will be resolved and your logs will be clean.
DEUF permanently modifies entity UUIDs in your save data. While this is safe and intentional, always back up your world before running any mod that alters saved entity data. If something goes wrong, you'll want to be able to restore.
How It Works
DEUF registers a single event handler that listens for chunk load events on the server side. Every time a chunk loads, the mod iterates through all entities in that chunk and checks each entity's UUID against the world's existing entity registry. If the UUID is already assigned to a different entity, the mod generates a fresh random UUID using Minecraft's built-in MathHelper and reassigns it.
The mod includes a safety loop: if the newly generated UUID also happens to conflict (extremely unlikely, but possible), it keeps generating new UUIDs until it finds one that's truly unique. Player entities are always excluded from UUID reassignment, so your player data is never touched.
Why Duplicate UUIDs Happen
Duplicate entity UUIDs are a vanilla Minecraft bug that Mojang has acknowledged but never fully resolved in 1.12.x. They most commonly appear in older worlds that have been through multiple Minecraft version upgrades, worlds with heavy chunk manipulation (WorldEdit, structure paste operations), or servers that have experienced crashes during world saves. Paintings, Item Frames, and Armor Stands are the most frequent culprits because they're persistent entities that often get duplicated during chunk boundary issues.
DEUF is marked with acceptableRemoteVersions="*", which means clients can join your server without having the mod installed. This makes it perfect for dedicated servers. You can install it server-side only and your players won't need to download anything.
Log Messages
Understanding the log output helps you verify DEUF is working correctly. Before installing the mod, you'll see repeated WARN-level messages like: "Keeping entity minecraft:painting that already exists with UUID [uuid]". These are Minecraft's default behavior when it encounters duplicate UUIDs, and the game simply discards the newer entity.
With DEUF installed, you'll see the same warnings followed by INFO-level messages from the [uuidfix] logger: "Changing UUID of entity minecraft:painting that already existed from [old-uuid] to [new-uuid]". Each of these INFO messages represents a permanent fix. On subsequent server restarts or chunk reloads, those specific entities will no longer trigger any warnings at all.
To see how many fixes DEUF has applied, search your server log for "[uuidfix]" after a play session. Each line represents one entity that was permanently fixed. Over time, these messages will decrease to zero as all duplicate UUIDs in explored chunks are resolved.
Compatibility
DEUF is designed for Minecraft 1.12.2 on Forge and is compatible with virtually any other mod. Since it only operates on chunk load events and modifies entity UUIDs, it doesn't interfere with mod-added entities, custom mob AI, or world generation. The mod safely skips Player entities, so it won't cause issues with player data, permissions systems, or player-tracking mods.
DEUF has no configuration file. It works immediately upon installation with no setup required. There are no commands, no GUI, and no in-game interface. It simply runs in the background and fixes problems as chunks load.
FAQ
Do my players need to install DEUF?
No. DEUF is server-side only. It's marked with acceptableRemoteVersions="*", meaning any client can connect regardless of whether they have the mod. This makes it ideal for dedicated servers.
Will this fix all duplicate UUIDs at once?
DEUF fixes entities as their chunks are loaded. If you have a large world, you'll need to visit (or force-load) all chunks for the mod to fix every duplicate. Chunks that haven't been loaded since installing the mod won't be fixed until someone visits them.
Can I remove the mod after it fixes my world?
Yes. Once DEUF has fixed the duplicate UUIDs in your explored chunks, the fixes are saved to the world data. You can safely remove the mod afterward. However, if new duplicate UUIDs are created (through world editing, crashes, or chunk corruption), the problem could return without the mod installed.
Does DEUF affect player UUIDs or player data?
No. The mod explicitly skips all Player entities. Only non-player entities (mobs, Paintings, Item Frames, Armor Stands, etc.) have their UUIDs reassigned when duplicates are detected.
Why are my logs bigger after installing DEUF?
On the first load, DEUF adds its own INFO messages alongside the existing WARN messages, temporarily increasing log output. Each INFO message confirms a UUID fix. After the affected chunks have been loaded and saved once, both the warnings and the fix messages will stop appearing for those entities.
Is DEUF compatible with SpongeForge or other server platforms?
DEUF uses standard Forge events (ChunkEvent.Load) and vanilla Minecraft methods, so it should work with any Forge-compatible server setup. It doesn't modify core classes or use mixins, minimizing the chance of conflicts with server platforms like SpongeForge.