{"record":{"id":"500b0b6deab83645","repo":"EllanJiang/GameFramework","slug":"download-agent-helper-is-invalid","errorCode":null,"errorMessage":"Download agent helper is invalid.","messagePattern":"Download agent helper is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Download/DownloadManager.DownloadAgent.cs","lineNumber":43,"sourceCode":"            private long m_StartLength;\n            private long m_DownloadedLength;\n            private long m_SavedLength;\n            private bool m_Disposed;\n\n            public GameFrameworkAction<DownloadAgent> DownloadAgentStart;\n            public GameFrameworkAction<DownloadAgent, int> DownloadAgentUpdate;\n            public GameFrameworkAction<DownloadAgent, long> DownloadAgentSuccess;\n            public GameFrameworkAction<DownloadAgent, string> DownloadAgentFailure;\n\n            /// <summary>\n            /// 初始化下载代理的新实例。\n            /// </summary>\n            /// <param name=\"downloadAgentHelper\">下载代理辅助器。</param>\n            public DownloadAgent(IDownloadAgentHelper downloadAgentHelper)\n            {\n                if (downloadAgentHelper == null)\n                {\n                    throw new GameFrameworkException(\"Download agent helper is invalid.\");\n                }\n\n                m_Helper = downloadAgentHelper;\n                m_Task = null;\n                m_FileStream = null;\n                m_WaitFlushSize = 0;\n                m_WaitTime = 0f;\n                m_StartLength = 0L;\n                m_DownloadedLength = 0L;\n                m_SavedLength = 0L;\n                m_Disposed = false;\n\n                DownloadAgentStart = null;\n                DownloadAgentUpdate = null;\n                DownloadAgentSuccess = null;\n                DownloadAgentFailure = null;\n            }\n","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Download/DownloadManager.DownloadAgent.cs#L25-L61","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom download helper failed to instantiate (missing dependency/DI misconfiguration), helper created conditionally and null on some platforms, or refactor changed helper creation order.","solutions":["Ensure a valid IDownloadAgentHelper instance is created before constructing the DownloadAgent","Check the helper factory/dependency injection setup for null returns","Verify the helper class compiles and is included for the target platform (e.g. not stripped by IL2CPP managed stripping)"],"exampleFix":"// before\nIDownloadAgentHelper helper = CreateHelper(); // may return null\nvar agent = new DownloadManager.DownloadAgent(helper);\n// after\nIDownloadAgentHelper helper = CreateHelper() ?? throw new InvalidOperationException(\"helper factory returned null\");\nvar agent = new DownloadManager.DownloadAgent(helper);","handlingStrategy":"type-guard","validationCode":"if (helper == null) throw new InvalidOperationException(\"Download agent helper must be created before the agent\");","typeGuard":"bool HasValidHelper(IDownloadAgentHelper helper) => helper != null;","tryCatchPattern":"try { var agent = new DownloadManager.DownloadAgent(helper); } catch (GameFrameworkException ex) { Log.Error(\"Failed to create download agent: {0}\", ex.Message); }","preventionTips":["Construct helpers via a factory that never returns null","Verify helper classes survive managed code stripping on IL2CPP","Check DI/factory logs when helper creation fails"],"tags":["download","null-argument","dependency","unity","gameframework"],"backgroundTag":"null-argument","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}