EllanJiang/GameFramework · error · GameFrameworkException

UI form instance is invalid.

Error message

UI form instance is invalid.

What it means

SetUIFormInstanceLocked toggles the instance-pool lock flag on the raw visual instance (GameObject) of a form so the pool will not recycle it. It throws this GameFrameworkException when the uiFormInstance object argument is null, because the InstancePool cannot operate on a null object.

Solutions

1. Null-check the instance before calling SetUIFormInstanceLocked
2. Obtain the instance via uiForm.gameObject or the form's Handle so it is guaranteed non-null
3. Fix the field/assignment that produced the null instance

Example fix

// before
UI.SetUIFormInstanceLocked(formRoot, true);
// after
if (formRoot != null)
{
    UI.SetUIFormInstanceLocked(formRoot, true);
}

if (instance == null || (instance is UnityEngine.Object uo && uo == null)) return;

bool IsAliveInstance(object o) => o != null && (!(o is UnityEngine.Object uo) || uo != null);

try { UI.SetUIFormInstanceLocked(instance, true); } catch (GameFrameworkException ex) { Log.Warning("Bad form instance: {0}", ex.Message); }

When it happens

Trigger: Calling SetUIFormInstanceLockeded(object, bool) with a null instance, typically a null GetComponent result, a null field on a form script, or null passed from an editor tool.

Common situations: Form prefab scripts forwarding form.gameObject before Awake assigned it; batch lock operations iterating a list containing destroyed (null) Unity objects.

Related errors

• Results is invalid.
• UI form asset is invalid.
• UI form helper is invalid.
• UI form is invalid.
• UI form is invalid.

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

Appendix: source

Thrown at GameFramework/UI/UIManager.cs:919

            {
                throw new GameFrameworkException("UI group is invalid.");
            }

            uiGroup.RefocusUIForm(uiForm, userData);
            uiGroup.Refresh();
            uiForm.OnRefocus(userData);
        }

        /// <summary>
        /// 设置界面实例是否被加锁。
        /// </summary>
        /// <param name="uiFormInstance">要设置是否被加锁的界面实例。</param>
        /// <param name="locked">界面实例是否被加锁。</param>
        public void SetUIFormInstanceLocked(object uiFormInstance, bool locked)
        {
            if (uiFormInstance == null)
            {
                throw new GameFrameworkException("UI form instance is invalid.");
            }

            m_InstancePool.SetLocked(uiFormInstance, locked);
        }

        /// <summary>
        /// 设置界面实例的优先级。
        /// </summary>
        /// <param name="uiFormInstance">要设置优先级的界面实例。</param>
        /// <param name="priority">界面实例优先级。</param>
        public void SetUIFormInstancePriority(object uiFormInstance, int priority)
        {
            if (uiFormInstance == null)
            {
                throw new GameFrameworkException("UI form instance is invalid.");
            }

            m_InstancePool.SetPriority(uiFormInstance, priority);

View on GitHub (pinned to d0c010b051)