EllanJiang/GameFramework · error · GameFrameworkException

UI group helper is invalid.

Error message

UI group helper is invalid.

What it means

The UIGroup constructor throws when the uiGroupHelper parameter is null. The group delegates depth sorting and form lifecycle operations to its helper, so a null helper makes the group non-functional from construction onward.

Solutions

1. Register/configure an IUIGroupHelper on UIComponent/UIManager before AddUIGroup (default UnityGameFramework does this via a scene component).
2. Pass the non-null helper instance when constructing UIGroup directly.
3. Verify scene setup: the helper component must exist under the UI/GameObject roots.

Example fix

// before
UIComponent.SetUIGroupHelper(null);
UIComponent.AddUIGroup("Main", 0);
// after
UIComponent.SetUIGroupHelper(gameObject.AddComponent<UIGroupHelper>());
UIComponent.AddUIGroup("Main", 0);

if (uiGroupHelper == null)
{
    Log.Error("UIGroup helper not configured before AddUIGroup");
    return;
}

try { UIComponent.AddUIGroup(groupName, depth); }
catch (GameFrameworkException ex) { Log.Error(ex, "UI group helper missing"); }

When it happens

Trigger: UIGroup constructed (via UIManager.AddUIGroup) while no IUIGroupHelper was configured — UIManager's helper field was never set, or null was passed explicitly.

Common situations: Forgot to register the UIGroupHelper component in the Unity scene; custom bootstrap creating groups before UIComponent initialization; SetUIGroupHelper never called.

Related errors

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

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

Appendix: source

Thrown at GameFramework/UI/UIManager.UIGroup.cs:41

            private readonly GameFrameworkLinkedList<UIFormInfo> m_UIFormInfos;
            private LinkedListNode<UIFormInfo> m_CachedNode;

            /// <summary>
            /// 初始化界面组的新实例。
            /// </summary>
            /// <param name="name">界面组名称。</param>
            /// <param name="depth">界面组深度。</param>
            /// <param name="uiGroupHelper">界面组辅助器。</param>
            public UIGroup(string name, int depth, IUIGroupHelper uiGroupHelper)
            {
                if (string.IsNullOrEmpty(name))
                {
                    throw new GameFrameworkException("UI group name is invalid.");
                }

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

                m_Name = name;
                m_Pause = false;
                m_UIGroupHelper = uiGroupHelper;
                m_UIFormInfos = new GameFrameworkLinkedList<UIFormInfo>();
                m_CachedNode = null;
                Depth = depth;
            }

            /// <summary>
            /// 获取界面组名称。
            /// </summary>
            public string Name
            {
                get
                {
                    return m_Name;

View on GitHub (pinned to d0c010b051)