sschmid/Entitas · error · Exception

EntityLink is already unlinked!

Error message

EntityLink is already unlinked!

What it means

EntityLink.Unlink throws this when _entity is already null, meaning the link was never established or was already released. Unlink would otherwise call entity.Release(this) with a null target and corrupt retain accounting.

Solutions

1. Only call Unlink when entityLink.entity != null
2. Remove manual Unlink calls that duplicate the automatic OnDestroy cleanup
3. Check link state in pooled-object reset code before unlinking

Example fix

// before
link.Unlink(); // throws if already unlinked
// after
if (link.entity != null) link.Unlink();

if (link.entity != null) link.Unlink();

bool IsLinked(EntityLink link) => link.entity != null;

When it happens

Trigger: Calling entityLink.Unlink() twice, calling Unlink on a fresh EntityLink that was never Linked, or OnDestroy running after Unlink was already called manually.

Common situations: Double teardown during Unity object destruction (manual Unlink in code plus OnDestroy auto-unlink), and pooled object cleanup scripts calling Unlink unconditionally.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• EntityLink is already linked to
• Cannot release !
• Cannot add component
• Unbalanced count with groups
• ContextInfoException(this, contextInfo)

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

Appendix: source

Thrown at src/Entitas.Unity/Entity/EntityLink.cs:25

    {
        public Entity Entity => _entity;

        Entity _entity;
        bool _applicationIsQuitting;

        public void Link(Entity entity)
        {
            if (_entity != null)
                throw new Exception($"EntityLink is already linked to {_entity}!");

            _entity = entity;
            _entity.Retain(this);
        }

        public void Unlink()
        {
            if (_entity == null)
                throw new Exception("EntityLink is already unlinked!");

            _entity.Release(this);
            _entity = null;
        }

        void OnDestroy()
        {
            if (!_applicationIsQuitting && _entity != null)
                Debug.LogWarning($"EntityLink got destroyed but is still linked to {_entity}!\nPlease call gameObject.Unlink() before it is destroyed.");
        }

        void OnApplicationQuit() => _applicationIsQuitting = true;

        public override string ToString() => $"EntityLink({gameObject.name})";
    }

    public static class EntityLinkExtension
    {

View on GitHub (pinned to 37547d1bd2)