sschmid/Entitas · error · EntityIsNotEnabledException

Cannot add component

Error message

Cannot add component '{_contextInfo.ComponentNames[index]}' to {this}!

What it means

Entity.AddComponent is only legal on an enabled entity that belongs to a context. When the entity has been destroyed (or not yet created via CreateEntity), it is disabled and adding a component is rejected because the component would attach to a dead/recycled entity.

Solutions

Check entity.isEnabled before adding components
Cancel deferred operations when the entity is destroyed (OnEntityWillBeDestroyed callbacks)
Re-create/re-fetch the entity from the context instead of reusing destroyed references
Use ReplaceComponent on live entities rather than stale handles

Example fix

// before
timerCallback = () => entity.AddPosition(0, 0); // entity may be destroyed
// after
timerCallback = () => {
    if (entity.isEnabled) entity.AddPosition(0, 0);
};

Defensive patterns

Strategy: type-guard

Validate before calling

if (!entity.isEnabled) return;
entity.AddComponent(index, component);

Type guard

bool CanAddComponent(IEntity e) => e.isEnabled;

Try / catch

try { entity.AddComponent(index, component); }
catch (EntityIsNotEnabledException) { /* entity destroyed — drop deferred work */ }

Prevention

Check isEnabled before deferred entity mutations
Cancel deferred callbacks on entity destruction
Re-fetch entities from context instead of caching across frames

When it happens

Trigger: Calling entity.AddComponent(index, component) (or generated AddX methods) on an entity after Destroy() or on a stale reference recycled by the context; also DrawComponents/debug paths invoked on destroyed entities.

Common situations: Deferred actions (tweens, timers, coroutines) holding an entity reference across destruction, event handlers firing after entity teardown, and pooled entities reused while old code still writes to them.

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

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

Appendix: source

Thrown at src/Entitas/Entity/Entity.cs:135

            return new ContextInfo("No Context", componentNames, null);
        }

        public void Reuse(int id)
        {
            _id = id;
            _isEnabled = true;
        }

        /// Adds a component at the specified index.
        /// You can only have one component at an index.
        /// Each component type must have its own constant index.
        /// The preferred way is to use the
        /// generated methods from the code generator.
        public void AddComponent(int index, IComponent component)
        {
            if (!_isEnabled)
                throw new EntityIsNotEnabledException($"Cannot add component '{_contextInfo.ComponentNames[index]}' to {this}!");

            if (HasComponent(index))
                throw new EntityAlreadyHasComponentException(index,
                    $"Cannot add component '{_contextInfo.ComponentNames[index]}' to {this}!",
                    "You should check if an entity already has the component before adding it or use entity.ReplaceComponent()."
                );

            _components[index] = component;
            _componentsCache = null;
            _componentIndexesCache = null;
            _toStringCache = null;
            OnComponentAdded?.Invoke(this, index, component);
        }

        /// Removes a component at the specified index.
        /// You can only remove a component at an index if it exists.
        /// The preferred way is to use the
        /// generated methods from the code generator.

View on GitHub (pinned to 37547d1bd2)