{"record":{"id":"b1fd3f9a93162fa4","repo":"EllanJiang/GameFramework","slug":"ui-form-instance-is-invalid","errorCode":null,"errorMessage":"UI form instance is invalid.","messagePattern":"UI form instance is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/UI/UIManager.cs","lineNumber":919,"sourceCode":"            {\n                throw new GameFrameworkException(\"UI group is invalid.\");\n            }\n\n            uiGroup.RefocusUIForm(uiForm, userData);\n            uiGroup.Refresh();\n            uiForm.OnRefocus(userData);\n        }\n\n        /// <summary>\n        /// 设置界面实例是否被加锁。\n        /// </summary>\n        /// <param name=\"uiFormInstance\">要设置是否被加锁的界面实例。</param>\n        /// <param name=\"locked\">界面实例是否被加锁。</param>\n        public void SetUIFormInstanceLocked(object uiFormInstance, bool locked)\n        {\n            if (uiFormInstance == null)\n            {\n                throw new GameFrameworkException(\"UI form instance is invalid.\");\n            }\n\n            m_InstancePool.SetLocked(uiFormInstance, locked);\n        }\n\n        /// <summary>\n        /// 设置界面实例的优先级。\n        /// </summary>\n        /// <param name=\"uiFormInstance\">要设置优先级的界面实例。</param>\n        /// <param name=\"priority\">界面实例优先级。</param>\n        public void SetUIFormInstancePriority(object uiFormInstance, int priority)\n        {\n            if (uiFormInstance == null)\n            {\n                throw new GameFrameworkException(\"UI form instance is invalid.\");\n            }\n\n            m_InstancePool.SetPriority(uiFormInstance, priority);","sourceCodeStart":901,"sourceCodeEnd":937,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/UI/UIManager.cs#L901-L937","documentation":"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.","triggerScenarios":"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.","commonSituations":"Form prefab scripts forwarding form.gameObject before Awake assigned it; batch lock operations iterating a list containing destroyed (null) Unity objects.","solutions":["Null-check the instance before calling SetUIFormInstanceLocked","Obtain the instance via uiForm.gameObject or the form's Handle so it is guaranteed non-null","Fix the field/assignment that produced the null instance"],"exampleFix":"// before\nUI.SetUIFormInstanceLocked(formRoot, true);\n// after\nif (formRoot != null)\n{\n    UI.SetUIFormInstanceLocked(formRoot, true);\n}","handlingStrategy":"type-guard","validationCode":"if (instance == null || (instance is UnityEngine.Object uo && uo == null)) return;","typeGuard":"bool IsAliveInstance(object o) => o != null && (!(o is UnityEngine.Object uo) || uo != null);","tryCatchPattern":"try { UI.SetUIFormInstanceLocked(instance, true); } catch (GameFrameworkException ex) { Log.Warning(\"Bad form instance: {0}\", ex.Message); }","preventionTips":["Use form.gameObject as the canonical instance handle","Check Unity destroyed-state (fake null) in addition to C# null","Assign instance fields in Awake, not OnEnable-dependent order"],"tags":["unity","gameframework","ui","instance-pool","null-argument"],"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"}