EllanJiang/GameFramework · error · GameFrameworkException

Entity is invalid.

Error message

Entity is invalid.

What it means

Parameter guard in EntityManager.HideEntity(IEntity, object): thrown when the entity argument is null. The entity manager cannot hide an entity it has no reference to, so the call is rejected up front instead of failing later during entity lookup; pass a valid IEntity obtained from the manager.

Solutions

1. Null-check the entity before calling HideEntity
2. Obtain the entity via GetEntity(id) and verify non-null first
3. Fix the code path that left the cached entity reference null

Example fix

// before
IEntity entity = GetCachedEntity();
m_EntityComponent.HideEntity(entity, null);
// after
IEntity entity = GetCachedEntity();
if (entity != null)
{
    m_EntityComponent.HideEntity(entity, null);
}

if (entity == null) return;

bool IsValidEntity(IEntity e) => e != null;

try { HideEntity(entity, userData); } catch (GameFrameworkException ex) when (ex.Message == "Entity is invalid.") { Debug.LogWarning("HideEntity called with null entity"); }

When it happens

Trigger: Calling HideEntity(IEntity, object) with a null entity reference.

Common situations: A cached entity field that was never assigned or was cleared; dictionary lookup returned null and was passed through; ShowEntitySuccess handler stored a null on failure path.

Related errors

• Child entity is invalid.
• Entity id ' ' is already exist.
• Entity ' ' is already being loaded.
• Entity group ' ' is not exist.
• Can not find entity ' '.

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

Appendix: source

Thrown at GameFramework/Entity/EntityManager.cs:708

        /// <summary>
        /// 隐藏实体。
        /// </summary>
        /// <param name="entity">实体。</param>
        public void HideEntity(IEntity entity)
        {
            HideEntity(entity, null);
        }

        /// <summary>
        /// 隐藏实体。
        /// </summary>
        /// <param name="entity">实体。</param>
        /// <param name="userData">用户自定义数据。</param>
        public void HideEntity(IEntity entity, object userData)
        {
            if (entity == null)
            {
                throw new GameFrameworkException("Entity is invalid.");
            }

            HideEntity(entity.Id, userData);
        }

        /// <summary>
        /// 隐藏所有已加载的实体。
        /// </summary>
        public void HideAllLoadedEntities()
        {
            HideAllLoadedEntities(null);
        }

        /// <summary>
        /// 隐藏所有已加载的实体。
        /// </summary>
        /// <param name="userData">用户自定义数据。</param>
        public void HideAllLoadedEntities(object userData)

View on GitHub (pinned to d0c010b051)