sschmid/Entitas · error · EntityIndexException

Entity for key ' ' already exists!

Error message

Entity for key '{key}' already exists!

What it means

Thrown by PrimaryEntityIndex.AddEntity when an entity already exists in the index for the given key. A primary entity index enforces a strict one-entity-per-key invariant (e.g. username -> entity), unlike a normal EntityIndex which supports multiple entities per key.

Solutions

1. Ensure the key is unique before creating the entity — check via index.TryGetEntity(key, out var e)
2. Use context.DestroyEntity(existing) before creating a new entity for the same key
3. Use a non-primary EntityIndex if multiple entities per key are actually allowed
4. Fix key-component generation so it cannot produce duplicates (e.g. auto-increment ids)

Example fix

// before
var e = context.CreateEntity();
e.AddUserName(requestedName); // throws if name already indexed
// after
if (!_index.TryGetEntity(requestedName, out var existing)) {
    var e = context.CreateEntity();
    e.AddUserName(requestedName);
} else {
    existing.ReplaceUserName(requestedName); // reuse or reject
}

if (!primaryIndex.TryGetEntity(key, out var existing)) { /* safe to add */ }

bool KeyIsFree(PrimaryEntityIndex<Entity, string> idx, string key) => !idx.TryGetEntity(key, out _);

try { index.AddEntity(key, entity); }
catch (EntityIndexException ex) { Debug.LogWarning($"duplicate primary key '{key}': {ex.Message}"); }

When it happens

Trigger: Creating a second entity whose key component (e.g. a primary key like Username or Id) resolves to a key that is already indexed; calling index.AddEntity manually for an existing key.

Common situations: Spawning two players with the same name/id; loading saved data twice so a duplicate key entity is created; resetting entities without clearing the index; code-generated key getters returning a constant for malformed components.

Understand the failure class

Background: "already exists" / EEXIST / FileAlreadyExistsException: what the 'file already exists' error means and how to fix it — this error's family across 37 libraries.

Related errors

• ContextEntityIndexDoesAlreadyExistException(this…
• ContextEntityIndexDoesNotExistException(this, name)
• Cannot remove component
• Cannot replace component
• Cannot get component

AI-assisted analysis of sschmid/Entitas@37547d1bd2 (2026-09-14). Data as JSON: /api/errors/8f1b580cf7ff9d1d. Report an issue: GitHub.

Appendix: source

Thrown at src/Entitas/EntityIndex/PrimaryEntityIndex.cs:69

            {
                if (entity.Aerc is SafeAERC safeAerc)
                {
                    if (safeAerc.Owners.Contains(this))
                        entity.Release(this);
                }
                else
                {
                    entity.Release(this);
                }
            }

            _index.Clear();
        }

        protected override void AddEntity(TKey key, TEntity entity)
        {
            if (_index.ContainsKey(key))
                throw new EntityIndexException(
                    $"Entity for key '{key}' already exists!",
                    "Only one entity for a primary key is allowed.");

            _index.Add(key, entity);

            if (entity.Aerc is SafeAERC safeAerc)
            {
                if (!safeAerc.Owners.Contains(this))
                    entity.Retain(this);
            }
            else
            {
                entity.Retain(this);
            }
        }

        protected override void RemoveEntity(TKey key, TEntity entity)
        {

View on GitHub (pinned to 37547d1bd2)