EllanJiang/GameFramework · critical · GameFrameworkException

Resource helper is invalid.

Error message

Resource helper is invalid.

What it means

LoadResourceAgent requires an IResourceHelper used for resource-related lookups (e.g. checking whether a resource exists / reading metadata). A null resourceHelper means the agent cannot resolve resources, so the constructor throws this validation error.

Solutions

1. Pass a valid IResourceHelper instance (e.g. DefaultResourceHelper) when initializing the resource module.
2. Verify the helper is constructed before ResourceComponent/ResourceManager initialization runs.
3. If using a custom helper, confirm the factory/registration path actually returns a non-null instance.
4. Log and fail fast during bootstrap if any resource-module dependency is null.

Example fix

// before
resourceManager.Initialize(resourceMode, helper: null, ...);
// after
IResourceHelper resourceHelper = new DefaultResourceHelper();
resourceManager.Initialize(resourceMode, resourceHelper, ...);

if (resourceHelper == null)
    throw new ArgumentNullException(nameof(resourceHelper));
// before init: Debug.Assert(resourceHelper != null, "IResourceHelper must be registered");

bool IsValidResourceHelper(IResourceHelper h) => h != null;

try
{
    resourceComponent.Initialize(...);
}
catch (GameFrameworkException ex) when (ex.Message.Contains("Resource helper"))
{
    Debug.LogError("Register an IResourceHelper before initializing the resource module.");
}

When it happens

Trigger: Constructing LoadResourceAgent (directly or via ResourceManager initialization) with null for the resourceHelper parameter — typically when the resource helper implementation was never registered with the resource module.

Common situations: Custom GameFramework setups replacing DefaultResourceHelper but failing to pass it into the resource initializer; wiring the helper after starting loads; copy-pasted initialization code omitting the helper argument.

Related errors

• Load resource agent helper is invalid.
• Resource loader is invalid.
• Decrypt resource callback is invalid.
• Task is invalid.
• Resource manager is invalid.

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

Appendix: source

Thrown at GameFramework/Resource/ResourceManager.ResourceLoader.LoadResourceAgent.cs:54

                /// <summary>
                /// 初始化加载资源代理的新实例。
                /// </summary>
                /// <param name="loadResourceAgentHelper">加载资源代理辅助器。</param>
                /// <param name="resourceHelper">资源辅助器。</param>
                /// <param name="resourceLoader">加载资源器。</param>
                /// <param name="readOnlyPath">资源只读区路径。</param>
                /// <param name="readWritePath">资源读写区路径。</param>
                /// <param name="decryptResourceCallback">解密资源回调函数。</param>
                public LoadResourceAgent(ILoadResourceAgentHelper loadResourceAgentHelper, IResourceHelper resourceHelper, ResourceLoader resourceLoader, string readOnlyPath, string readWritePath, DecryptResourceCallback decryptResourceCallback)
                {
                    if (loadResourceAgentHelper == null)
                    {
                        throw new GameFrameworkException("Load resource agent helper is invalid.");
                    }

                    if (resourceHelper == null)
                    {
                        throw new GameFrameworkException("Resource helper is invalid.");
                    }

                    if (resourceLoader == null)
                    {
                        throw new GameFrameworkException("Resource loader is invalid.");
                    }

                    if (decryptResourceCallback == null)
                    {
                        throw new GameFrameworkException("Decrypt resource callback is invalid.");
                    }

                    m_Helper = loadResourceAgentHelper;
                    m_ResourceHelper = resourceHelper;
                    m_ResourceLoader = resourceLoader;
                    m_ReadOnlyPath = readOnlyPath;
                    m_ReadWritePath = readWritePath;
                    m_DecryptResourceCallback = decryptResourceCallback;

View on GitHub (pinned to d0c010b051)