{"record":{"id":"63692bc6da02beac","repo":"sschmid/Entitas","slug":"entitylink-is-already-linked-to-entity","errorCode":null,"errorMessage":"EntityLink is already linked to {_entity}!","messagePattern":"EntityLink is already linked to (.+?)!","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"src/Entitas.Unity/Entity/EntityLink.cs","lineNumber":16,"sourceCode":"using System;\nusing UnityEngine;\n\nnamespace Entitas.Unity\n{\n    public class EntityLink : MonoBehaviour\n    {\n        public Entity Entity => _entity;\n\n        Entity _entity;\n        bool _applicationIsQuitting;\n\n        public void Link(Entity entity)\n        {\n            if (_entity != null)\n                throw new Exception($\"EntityLink is already linked to {_entity}!\");\n\n            _entity = entity;\n            _entity.Retain(this);\n        }\n\n        public void Unlink()\n        {\n            if (_entity == null)\n                throw new Exception(\"EntityLink is already unlinked!\");\n\n            _entity.Release(this);\n            _entity = null;\n        }\n\n        void OnDestroy()\n        {\n            if (!_applicationIsQuitting && _entity != null)\n                Debug.LogWarning($\"EntityLink got destroyed but is still linked to {_entity}!\\nPlease call gameObject.Unlink() before it is destroyed.\");","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/sschmid/Entitas/blob/37547d1bd280f3f1c1ef7edb44f2a206660fbfb4/src/Entitas.Unity/Entity/EntityLink.cs#L1-L34","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call entityLink.Unlink() before Link(entity) when the link may already exist","Guard with a null check: only Link when GetEntityLink(...).entity == null","Reset/reset pooled GameObjects so EntityLink is unlinked on reuse","If intentionally re-linking, Unlink then Link in the same code path"],"exampleFix":"// before\ngameObject.GetEntityLink().Link(newEntity); // throws if already linked\n// after\nvar link = gameObject.GetEntityLink();\nif (link.entity != null) link.Unlink();\nlink.Link(newEntity);","handlingStrategy":"validation","validationCode":"if (link.entity != null) link.Unlink();\nlink.Link(entity);","typeGuard":"bool IsLinkable(EntityLink link) => link.entity == null;","tryCatchPattern":null,"preventionTips":["Always Unlink before re-Linking","Initialize/uninitialize EntityLink symmetrically in pooled objects","Add assertions in debug builds that link state matches GameObject lifecycle"],"tags":["unity","entitas","lifecycle","double-link"],"backgroundTag":"invalid-state-transition","analyzedSha":"37547d1bd280f3f1c1ef7edb44f2a206660fbfb4","analyzedAt":"2026-09-14T00:26:23.246Z","contentChangedAt":"2026-09-14T00:26:23.246Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}