sschmid/Entitas · error · Exception

EntityLink is already linked to

Error message

EntityLink is already linked to {_entity}!

What it means

EntityLink.Link throws this when the EntityLink instance already holds a reference to a different entity. Entitas guards against re-linking because Link calls entity.Retain(this) and the old entity would leak a retain count that is never released.

Solutions

1. Call entityLink.Unlink() before Link(entity) when the link may already exist
2. Guard with a null check: only Link when GetEntityLink(...).entity == null
3. Reset/reset pooled GameObjects so EntityLink is unlinked on reuse
4. If intentionally re-linking, Unlink then Link in the same code path

Example fix

// before
gameObject.GetEntityLink().Link(newEntity); // throws if already linked
// after
var link = gameObject.GetEntityLink();
if (link.entity != null) link.Unlink();
link.Link(newEntity);

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

bool IsLinkable(EntityLink link) => link.entity == null;

When it happens

Trigger: Calling entityLink.Link(entity) on an EntityLink that is already linked (its internal _entity != null) without first calling Unlink(), e.g. re-parenting a GameObject to another entity's EntityLink component.

Common situations: Unity developers moving an EntityLink MonoBehaviour between GameObjects, reusing pooled GameObjects across entities, or calling Link again after scene reloads where OnDestroy cleanup didn't run.

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 unlinked!
• 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/63692bc6da02beac. Report an issue: GitHub.

Appendix: source

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

using System;
using UnityEngine;

namespace Entitas.Unity
{
    public class EntityLink : MonoBehaviour
    {
        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.");

View on GitHub (pinned to 37547d1bd2)