EllanJiang/GameFramework · error · GameFrameworkException

Download agent helper is invalid.

Error message

Download agent helper is invalid.

What it means

DownloadManager.DownloadAgent's constructor requires a non-null IDownloadAgentHelper; the agent delegates all actual transfer work to this helper. A null helper means the agent could never download anything, so the constructor fails fast with this error.

Solutions

1. Ensure a valid IDownloadAgentHelper instance is created before constructing the DownloadAgent
2. Check the helper factory/dependency injection setup for null returns
3. Verify the helper class compiles and is included for the target platform (e.g. not stripped by IL2CPP managed stripping)

Example fix

// before
IDownloadAgentHelper helper = CreateHelper(); // may return null
var agent = new DownloadManager.DownloadAgent(helper);
// after
IDownloadAgentHelper helper = CreateHelper() ?? throw new InvalidOperationException("helper factory returned null");
var agent = new DownloadManager.DownloadAgent(helper);

if (helper == null) throw new InvalidOperationException("Download agent helper must be created before the agent");

bool HasValidHelper(IDownloadAgentHelper helper) => helper != null;

try { var agent = new DownloadManager.DownloadAgent(helper); } catch (GameFrameworkException ex) { Log.Error("Failed to create download agent: {0}", ex.Message); }

When it happens

Trigger: Constructing DownloadManager.DownloadAgent (or registering an agent through DownloadManager with a helper that is null), e.g. passing an uninitialized helper variable or a factory method that returned null.

Common situations: Custom download helper failed to instantiate (missing dependency/DI misconfiguration), helper created conditionally and null on some platforms, or refactor changed helper creation order.

Related errors

• Task is invalid.
• Task agent is invalid.
• Results is invalid.
• Offset is invalid.
• Length is invalid.

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

Appendix: source

Thrown at GameFramework/Download/DownloadManager.DownloadAgent.cs:43

            private long m_StartLength;
            private long m_DownloadedLength;
            private long m_SavedLength;
            private bool m_Disposed;

            public GameFrameworkAction<DownloadAgent> DownloadAgentStart;
            public GameFrameworkAction<DownloadAgent, int> DownloadAgentUpdate;
            public GameFrameworkAction<DownloadAgent, long> DownloadAgentSuccess;
            public GameFrameworkAction<DownloadAgent, string> DownloadAgentFailure;

            /// <summary>
            /// 初始化下载代理的新实例。
            /// </summary>
            /// <param name="downloadAgentHelper">下载代理辅助器。</param>
            public DownloadAgent(IDownloadAgentHelper downloadAgentHelper)
            {
                if (downloadAgentHelper == null)
                {
                    throw new GameFrameworkException("Download agent helper is invalid.");
                }

                m_Helper = downloadAgentHelper;
                m_Task = null;
                m_FileStream = null;
                m_WaitFlushSize = 0;
                m_WaitTime = 0f;
                m_StartLength = 0L;
                m_DownloadedLength = 0L;
                m_SavedLength = 0L;
                m_Disposed = false;

                DownloadAgentStart = null;
                DownloadAgentUpdate = null;
                DownloadAgentSuccess = null;
                DownloadAgentFailure = null;
            }

View on GitHub (pinned to d0c010b051)