What causes "UI form helper is invalid." in EllanJiang/GameFramework?

Pass a non-null IUIFormHelper instance, e.g. m_UIManager.SetUIFormHelper(new UGUIFormHelper())

EllanJiang/GameFramework · error · GameFrameworkException

UI form helper is invalid.

Error message

UI form helper is invalid.

What it means

GameFramework's UIManager requires an IUIFormHelper before it can open, close, or manage UI forms. SetUIFormHelper throws this GameFrameworkException when the helper argument is null, because every later UI form operation delegates to m_UIFormHelper and would crash with a NullReferenceException anyway. The throw is an early, explicit fail-fast for a missing mandatory dependency.

Solutions

Pass a non-null IUIFormHelper instance, e.g. m_UIManager.SetUIFormHelper(new UGUIFormHelper())
If the helper is created lazily, ensure it is instantiated before calling SetUIFormHelper or skip the call until it exists
Check that your DI/initialization order constructs the UI helper before the UIManager setup step
Wrap the call in a null check to fail with a clearer application-level message

Example fix

// before
UIManager.SetUIFormHelper(m_Config.uiFormHelper); // field may be null
// after
var helper = new UGUIFormHelper();
UIManager.SetUIFormHelper(helper);

Defensive patterns

Strategy: validation

Validate before calling

if (uiFormHelper == null) throw new InvalidOperationException("UIFormHelper must be created before SetUIFormHelper");
uiManager.SetUIFormHelper(uiFormHelper);

Type guard

bool IsValidHelper(IUIFormHelper h) => h != null;

Try / catch

try { uiManager.SetUIFormHelper(helper); }
catch (GameFrameworkException ex) { Debug.LogError($"UI init failed: {ex.Message}"); }

Prevention

Create the UI helper at the very start of the framework initialization sequence
Never pass helper references obtained from fields that may not be assigned yet
Add an assertion in your game entry that all helpers are constructed before UIManager setup

When it happens

Trigger: Calling SetUIFormHelper(null), typically when helper initialization is conditional or the helper field is not yet assigned at the call site.

Common situations: Bootstrap code where the IUIFormHelper implementation is created after the UIManager is used; Unity projects that forgot to register a custom UIFormHelper in their game entry script; refactoring that removed the helper creation but left the SetUIFormHelper call.

Related errors

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

Appendix: source

Thrown at GameFramework/UI/UIManager.cs:276

        public void SetResourceManager(IResourceManager resourceManager)
        {
            if (resourceManager == null)
            {
                throw new GameFrameworkException("Resource manager is invalid.");
            }

            m_ResourceManager = resourceManager;
        }

        /// <summary>
        /// 设置界面辅助器。
        /// </summary>
        /// <param name="uiFormHelper">界面辅助器。</param>
        public void SetUIFormHelper(IUIFormHelper uiFormHelper)
        {
            if (uiFormHelper == null)
            {
                throw new GameFrameworkException("UI form helper is invalid.");
            }

            m_UIFormHelper = uiFormHelper;
        }

        /// <summary>
        /// 是否存在界面组。
        /// </summary>
        /// <param name="uiGroupName">界面组名称。</param>
        /// <returns>是否存在界面组。</returns>
        public bool HasUIGroup(string uiGroupName)
        {
            if (string.IsNullOrEmpty(uiGroupName))
            {
                throw new GameFrameworkException("UI group name is invalid.");
            }

            return m_UIGroups.ContainsKey(uiGroupName);

View on GitHub (pinned to d0c010b051)