sschmid/Entitas · error · EntityIsNotRetainedByOwnerException

EntityIsNotRetainedByOwnerException(_entity, owner)

Error message

EntityIsNotRetainedByOwnerException(_entity, owner)

What it means

Thrown by SafeAERC.Release when the given owner does not currently retain the entity (Owners.Remove returns false). Every Release must be paired with a prior Retain by the same owner; releasing unbalanced would drop someone else's reference count.

Solutions

1. Ensure Retain(owner) was called before Release(owner) — pair them in acquire/remove code paths
2. Guard release logic with entity.Owners.Contains(owner) (SafeAERC) before releasing
3. Keep retention symmetric: retain in add-to-collection, release in remove-from-collection
4. Audit Retain/Release call sites to confirm the same owner instance is used

Example fix

// before
void OnEntityRemoved(Entity e) { e.Release(this); _list.Remove(e); } // throws if never retained
// after
void OnEntityRemoved(Entity e) {
    if (_list.Remove(e)) {
        e.Release(this);
    }
}

if (entity.Aerc is SafeAERC sa && sa.Owners.Contains(owner)) entity.Release(owner);

bool CanRelease(Entity e, object owner) => e.Aerc is SafeAERC sa && sa.Owners.Contains(owner);

try { entity.Release(owner); }
catch (EntityIsNotRetainedByOwnerException) { /* never retained by this owner */ }

When it happens

Trigger: Calling entity.Release(owner) without a matching earlier Retain(owner); releasing twice; a teardown path that releases entities never retained; releasing after the retain bookkeeping was reset.

Common situations: Destroy handlers releasing entities retained elsewhere; systems destroyed before they retained; mixed use of UnsafeAERC/SafeAERC where retains were not recorded.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• EntityIsAlreadyRetainedByOwnerException(_entity, owner)
• Cannot remove component
• Cannot replace component
• Cannot get component
• Cannot destroy !

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

Appendix: source

Thrown at src/Entitas/Entity/SafeAERC.cs:37

        readonly Entity _entity;
        readonly HashSet<object> _owners = new HashSet<object>();

        public SafeAERC(Entity entity)
        {
            _entity = entity;
        }

        public void Retain(object owner)
        {
            if (!Owners.Add(owner))
                throw new EntityIsAlreadyRetainedByOwnerException(_entity, owner);
        }

        public void Release(object owner)
        {
            if (!Owners.Remove(owner))
                throw new EntityIsNotRetainedByOwnerException(_entity, owner);
        }
    }
}

View on GitHub (pinned to 37547d1bd2)