EllanJiang/GameFramework · error · GameFrameworkException

Can not create UI form in UI form helper.

Error message

Can not create UI form in UI form helper.

What it means

During InternalOpenUIForm, UIManager asks the registered IUIFormHelper to create the form object from the loaded instance. If the helper returns null the framework cannot continue and throws this GameFrameworkException. It indicates the UI form helper (usually UIFormHelper on the Unity side) failed to build the form component.

Solutions

  1. Ensure the form prefab has a UIForm-derived component and the custom logic script attached
  2. Check your IUIFormHelper.CreateUIForm implementation returns non-null or throws a descriptive error
  3. Verify the UIFormHelper assigned on UIComponent in the inspector is the correct type
  4. Log the loaded asset name inside CreateUIForm to find which prefab is broken

Example fix

// before (custom helper)
return instance as UIForm;
// after
var form = (instance as GameObject)?.GetComponent<UIFormLogic>();
if (form == null)
{
    Log.Error("UIForm component missing on prefab");
}
return form;
Defensive patterns

Strategy: validation

Validate before calling

var form = loadedInstance as GameObject;
if (form == null || form.GetComponent<UIFormLogic>() == null)
{
    Log.Error("Prefab {0} missing UIFormLogic", form ? form.name : loadedInstance);
    return;
}

Try / catch

try { UI.OpenUIForm(assetName, group, userData); } catch (GameFrameworkException ex) { Log.Error("UIFormHelper failed: {0}", ex.Message); }

Prevention

When it happens

Trigger: CreateUIForm in the custom helper returning null: the loaded asset has no UIForm-derived component (Instantiate added it but GetComponent<UIForm> fails), a custom helper script returns null on error, or the wrong helper is assigned on UIComponent.

Common situations: Prefab built without the UIForm script after a refactor; a custom helper expecting a different instance type (e.g. receiving a GameObject but casting to wrong type and swallowing the exception); helper's InstantiateLogic not attached.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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

Appendix: source

Thrown at GameFramework/UI/UIManager.cs:947

        /// <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);
        }

        private void InternalOpenUIForm(int serialId, string uiFormAssetName, UIGroup uiGroup, object uiFormInstance, bool pauseCoveredUIForm, bool isNewInstance, float duration, object userData)
        {
            try
            {
                IUIForm uiForm = m_UIFormHelper.CreateUIForm(uiFormInstance, uiGroup, userData);
                if (uiForm == null)
                {
                    throw new GameFrameworkException("Can not create UI form in UI form helper.");
                }

                uiForm.OnInit(serialId, uiFormAssetName, uiGroup, pauseCoveredUIForm, isNewInstance, userData);
                uiGroup.AddUIForm(uiForm);
                uiForm.OnOpen(userData);
                uiGroup.Refresh();

                if (m_OpenUIFormSuccessEventHandler != null)
                {
                    OpenUIFormSuccessEventArgs openUIFormSuccessEventArgs = OpenUIFormSuccessEventArgs.Create(uiForm, duration, userData);
                    m_OpenUIFormSuccessEventHandler(this, openUIFormSuccessEventArgs);
                    ReferencePool.Release(openUIFormSuccessEventArgs);
                }
            }
            catch (Exception exception)
            {
                if (m_OpenUIFormFailureEventHandler != null)
                {

View on GitHub (pinned to d0c010b051)