EllanJiang/GameFramework · error · GameFrameworkException

Entity helper is invalid.

Error message

Entity helper is invalid.

What it means

EntityInstanceObject.Create also validates the IEntityHelper argument and throws GameFrameworkException when it is null. The helper drives init/show/hide/release of the entity instance, so without it the pooled object cannot function. Usually means the entity component's helper was never assigned.

Solutions

1. Assign a non-null EntityHelper implementation to the EntityComponent (Inspector or code) before showing entities.
2. If calling Create manually, pass the same helper the entity manager uses.
3. Add an init-order check that the helper is configured before any ShowEntity call.

Example fix

// before
entityComponent.EntityHelper = null; // or never set
entityManager.ShowEntity(id);
// after
entityComponent.EntityHelper = new MyEntityHelper();
entityManager.ShowEntity(id);

if (entityHelper == null) throw new InvalidOperationException("EntityHelper not assigned");
var obj = EntityInstanceObject.Create(name, entityAsset, entityInstance, entityHelper);

bool HasHelper(IEntityHelper helper) => helper != null;

try { var obj = EntityInstanceObject.Create(name, entityAsset, instance, helper); }
catch (GameFrameworkException ex) { Log.Error("Instance object create failed: {0}", ex.Message); }

When it happens

Trigger: Calling EntityInstanceObject.Create with a null entityHelper, or using an EntityManager/EntityComponent whose EntityHelper property was not set before ShowEntity.

Common situations: Forgetting to add/assign a class deriving from EntityHelper to the Unity EntityComponent in the Inspector; helper assigned only in code that did not run (early init order issue); refactoring removed the helper registration.

Related errors

• Owner is invalid.
• Resource manager is invalid.
• Data provider helper is invalid.
• Type is invalid.
• Event is invalid.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/9578566afdabb87d. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/Entity/EntityManager.EntityInstanceObject.cs:37

            private object m_EntityAsset;
            private IEntityHelper m_EntityHelper;

            public EntityInstanceObject()
            {
                m_EntityAsset = null;
                m_EntityHelper = null;
            }

            public static EntityInstanceObject Create(string name, object entityAsset, object entityInstance, IEntityHelper entityHelper)
            {
                if (entityAsset == null)
                {
                    throw new GameFrameworkException("Entity asset is invalid.");
                }

                if (entityHelper == null)
                {
                    throw new GameFrameworkException("Entity helper is invalid.");
                }

                EntityInstanceObject entityInstanceObject = ReferencePool.Acquire<EntityInstanceObject>();
                entityInstanceObject.Initialize(name, entityInstance);
                entityInstanceObject.m_EntityAsset = entityAsset;
                entityInstanceObject.m_EntityHelper = entityHelper;
                return entityInstanceObject;
            }

            public override void Clear()
            {
                base.Clear();
                m_EntityAsset = null;
                m_EntityHelper = null;
            }

            protected internal override void Release(bool isShutdown)
            {

View on GitHub (pinned to d0c010b051)