{"record":{"id":"112fd258c3ea56f1","repo":"EllanJiang/GameFramework","slug":"entity-instance-is-invalid","errorCode":null,"errorMessage":"Entity instance is invalid.","messagePattern":"Entity instance is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Entity/EntityManager.EntityGroup.cs","lineNumber":377,"sourceCode":"            {\n                m_InstancePool.Register(obj, spawned);\n            }\n\n            public EntityInstanceObject SpawnEntityInstanceObject(string name)\n            {\n                return m_InstancePool.Spawn(name);\n            }\n\n            public void UnspawnEntity(IEntity entity)\n            {\n                m_InstancePool.Unspawn(entity.Handle);\n            }\n\n            public void SetEntityInstanceLocked(object entityInstance, bool locked)\n            {\n                if (entityInstance == null)\n                {\n                    throw new GameFrameworkException(\"Entity instance is invalid.\");\n                }\n\n                m_InstancePool.SetLocked(entityInstance, locked);\n            }\n\n            public void SetEntityInstancePriority(object entityInstance, int priority)\n            {\n                if (entityInstance == null)\n                {\n                    throw new GameFrameworkException(\"Entity instance is invalid.\");\n                }\n\n                m_InstancePool.SetPriority(entityInstance, priority);\n            }\n        }\n    }\n}\n","sourceCodeStart":359,"sourceCodeEnd":395,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Entity/EntityManager.EntityGroup.cs#L359-L395","documentation":"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.","triggerScenarios":"Calling EntityGroup.SetEntityInstanceLocked(null, true), or via EntityManager.SetInstanceLocked with an instance object obtained from a failed/empty pool lookup.","commonSituations":"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.","solutions":["Verify the instance object is non-null before calling SetEntityInstanceLocked.","Confirm you are passing the pooled instance object (from the instance pool), not the raw asset or entity.","If the instance may have been released, re-acquire it from the pool first."],"exampleFix":"// before\nentityManager.SetInstanceLocked(groupId, instance, true); // instance may be null\n// after\nif (instance != null)\n{\n    entityManager.SetInstanceLocked(groupId, instance, true);\n}","handlingStrategy":"validation","validationCode":"if (entityInstance == null) return;\ngroup.SetEntityInstanceLocked(entityInstance, locked);","typeGuard":"bool HasValidInstance(object entityInstance) => entityInstance != null;","tryCatchPattern":"try { group.SetEntityInstanceLocked(entityInstance, true); }\ncatch (GameFrameworkException ex) { Log.Error(\"SetInstanceLocked failed: {0}\", ex.Message); }","preventionTips":["Null-check pooled instance references before use","Don't cache instance references across scene reloads","Pass the pooled instance object, not the raw asset"],"tags":["csharp","gameframework","null-argument","instance-pool"],"backgroundTag":"null-argument","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}