EllanJiang/GameFramework · error · GameFrameworkException

UI group helper is invalid.

Error message

UI group helper is invalid.

What it means

AddUIGroup requires an IUIGroupHelper to create the underlying group; it throws this GameFrameworkException when the uiGroupHelper argument is null. The helper handles the platform-specific instantiation of UI group objects, so a null helper would break group creation immediately after registration. The name check runs first, then this check, then the duplicate-name short-circuit.

Solutions

1. Pass a constructed helper, e.g. ui.AddUIGroup("Main", 1, new UIGroupHelper())
2. Verify helper initialization ran before group registration in the startup sequence
3. Check platform-conditional code paths so the helper exists on all target platforms
4. Create the helper inline in AddUIGroup calls if no shared instance is needed

Example fix

// before
IUIGroupHelper helper = CreateHelper(); // may return null on this platform
ui.AddUIGroup("Main", 1, helper);
// after
IUIGroupHelper helper = CreateHelper() ?? new DefaultUIGroupHelper();
ui.AddUIGroup("Main", 1, helper);

if (uiGroupHelper == null)
    uiGroupHelper = new DefaultUIGroupHelper();
uiManager.AddUIGroup(groupName, depth, uiGroupHelper);

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

try { uiManager.AddUIGroup(name, depth, helper); }
catch (GameFrameworkException ex) { Debug.LogError($"AddUIGroup failed: {ex.Message}"); }

When it happens

Trigger: Calling AddUIGroup(name, depth, null) — usually because the helper factory returned null, or setup code passes a helper obtained from an unassigned field.

Common situations: Unity projects that forgot to construct their UGUI/UICustomGroupHelper before registering groups; conditional platform code that only creates the helper on some platforms; DI containers that resolved the helper to null.

Related errors

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

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

Appendix: source

Thrown at GameFramework/UI/UIManager.cs:379

        }

        /// <summary>
        /// 增加界面组。
        /// </summary>
        /// <param name="uiGroupName">界面组名称。</param>
        /// <param name="uiGroupDepth">界面组深度。</param>
        /// <param name="uiGroupHelper">界面组辅助器。</param>
        /// <returns>是否增加界面组成功。</returns>
        public bool AddUIGroup(string uiGroupName, int uiGroupDepth, IUIGroupHelper uiGroupHelper)
        {
            if (string.IsNullOrEmpty(uiGroupName))
            {
                throw new GameFrameworkException("UI group name is invalid.");
            }

            if (uiGroupHelper == null)
            {
                throw new GameFrameworkException("UI group helper is invalid.");
            }

            if (HasUIGroup(uiGroupName))
            {
                return false;
            }

            m_UIGroups.Add(uiGroupName, new UIGroup(uiGroupName, uiGroupDepth, uiGroupHelper));

            return true;
        }

        /// <summary>
        /// 是否存在界面。
        /// </summary>
        /// <param name="serialId">界面序列编号。</param>
        /// <returns>是否存在界面。</returns>
        public bool HasUIForm(int serialId)

View on GitHub (pinned to d0c010b051)