EllanJiang/GameFramework · error · GameFrameworkException

Entity instance is invalid.

Error message

Entity instance is invalid.

What it means

SetEntityInstanceLocked forwards a lock flag to the group's instance pool but first validates the entity instance object. A null instance cannot be locked, so the library throws GameFrameworkException immediately. The instance pool manages cached entity instance objects; locking prevents them from being released.

Solutions

1. Verify the instance object is non-null before calling SetEntityInstanceLocked.
2. Confirm you are passing the pooled instance object (from the instance pool), not the raw asset or entity.
3. If the instance may have been released, re-acquire it from the pool first.

Example fix

// before
entityManager.SetInstanceLocked(groupId, instance, true); // instance may be null
// after
if (instance != null)
{
    entityManager.SetInstanceLocked(groupId, instance, true);
}

if (entityInstance == null) return;
group.SetEntityInstanceLocked(entityInstance, locked);

bool HasValidInstance(object entityInstance) => entityInstance != null;

try { group.SetEntityInstanceLocked(entityInstance, true); }
catch (GameFrameworkException ex) { Log.Error("SetInstanceLocked failed: {0}", ex.Message); }

When it happens

Trigger: Calling EntityGroup.SetEntityInstanceLocked(null, true), or via EntityManager.SetInstanceLocked with an instance object obtained from a failed/empty pool lookup.

Common situations: Caching the result of an instance lookup that returned null and later calling SetInstanceLocked with it; passing the entity instance (game object) instead of the pooled EntityInstanceObject; racing pool release so the object was already returned.

Related errors

• Code is invalid.
• Data provider helper is invalid.
• Data row type is invalid.
• Download manager is invalid.
• Entity asset is invalid.

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

Appendix: source

Thrown at GameFramework/Entity/EntityManager.EntityGroup.cs:377

            {
                m_InstancePool.Register(obj, spawned);
            }

            public EntityInstanceObject SpawnEntityInstanceObject(string name)
            {
                return m_InstancePool.Spawn(name);
            }

            public void UnspawnEntity(IEntity entity)
            {
                m_InstancePool.Unspawn(entity.Handle);
            }

            public void SetEntityInstanceLocked(object entityInstance, bool locked)
            {
                if (entityInstance == null)
                {
                    throw new GameFrameworkException("Entity instance is invalid.");
                }

                m_InstancePool.SetLocked(entityInstance, locked);
            }

            public void SetEntityInstancePriority(object entityInstance, int priority)
            {
                if (entityInstance == null)
                {
                    throw new GameFrameworkException("Entity instance is invalid.");
                }

                m_InstancePool.SetPriority(entityInstance, priority);
            }
        }
    }
}

View on GitHub (pinned to d0c010b051)