EllanJiang/GameFramework · critical · GameFrameworkException

Load resource agent helper is invalid.

Error message

Load resource agent helper is invalid.

What it means

The LoadResourceAgent constructor validates that a usable ILoadResourceAgentHelper was supplied; this helper actually performs the low-level loading (open stream, read bytes, load asset, etc.). If the helper reference is null the agent could never do any work, so GameFramework throws immediately during construction.

Solutions

1. Ensure an ILoadResourceAgentHelper implementation (e.g. DefaultLoadResourceAgentHelper) is created and passed when initializing the ResourceManager/ResourceLoader.
2. Check initialization order: build the resource agent helper before calling LoadAsset / setting up resource agents.
3. If using a custom helper, verify it is not conditionally skipped (platform defines, config) leaving it null.
4. Add a startup assertion that the helper is registered to fail fast at boot instead of at first load.

Example fix

// before
m_ResourceManager.LoadAsset(assetInfo, null); // helper missing
// after
DefaultLoadResourceAgentHelper helper = new DefaultLoadResourceAgentHelper();
m_ResourceManager.LoadAsset(assetInfo, helper);

if (loadResourceAgentHelper == null)
    throw new ArgumentNullException(nameof(loadResourceAgentHelper));
// or before initializing: Debug.Assert(resourceAgentHelper != null, "Resource agent helper must be set before loading resources");

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

try
{
    resourceComponent.LoadAsset(assetName, typeof(GameObject), onLoad);
}
catch (GameFrameworkException ex)
{
    // re-initialize resource module with a DefaultLoadResourceAgentHelper
    Debug.LogError($"Resource init failed: {ex.Message}");
}

When it happens

Trigger: Calling ResourceManager's LoadAsset/LoadAssetAsync machinery (via LoadResourceAgent ctor) with a null ILoadResourceAgentHelper — e.g. constructing the resource agent helper after/instead of passing it, or a DI/initialization order bug where m_ResourceAgentHelper has not been created.

Common situations: Customizing GameFramework's resource component and forgetting to set the resource agent helper; incorrect initialization order where ResourceManager is set up before the helper implementation (e.g. DefaultLoadResourceAgentHelper) is instantiated; refactoring that removed the helper assignment in the game's resource extension.

Related errors

• Resource 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/91507b49dfbe6aa4. Report an issue: GitHub.

Appendix: source

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

                private readonly string m_ReadOnlyPath;
                private readonly string m_ReadWritePath;
                private readonly DecryptResourceCallback m_DecryptResourceCallback;
                private LoadResourceTaskBase m_Task;

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

View on GitHub (pinned to d0c010b051)