{"record":{"id":"b65261a12566f535","repo":"EllanJiang/GameFramework","slug":"you-must-add-download-agent-first","errorCode":null,"errorMessage":"You must add download agent first.","messagePattern":"You must add download agent first\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Download/DownloadManager.cs","lineNumber":408,"sourceCode":"        /// <param name=\"tag\">下载任务的标签。</param>\n        /// <param name=\"priority\">下载任务的优先级。</param>\n        /// <param name=\"userData\">用户自定义数据。</param>\n        /// <returns>新增下载任务的序列编号。</returns>\n        public int AddDownload(string downloadPath, string downloadUri, string tag, int priority, object userData)\n        {\n            if (string.IsNullOrEmpty(downloadPath))\n            {\n                throw new GameFrameworkException(\"Download path is invalid.\");\n            }\n\n            if (string.IsNullOrEmpty(downloadUri))\n            {\n                throw new GameFrameworkException(\"Download uri is invalid.\");\n            }\n\n            if (TotalAgentCount <= 0)\n            {\n                throw new GameFrameworkException(\"You must add download agent first.\");\n            }\n\n            DownloadTask downloadTask = DownloadTask.Create(downloadPath, downloadUri, tag, priority, m_FlushSize, m_Timeout, userData);\n            m_TaskPool.AddTask(downloadTask);\n            return downloadTask.SerialId;\n        }\n\n        /// <summary>\n        /// 根据下载任务的序列编号移除下载任务。\n        /// </summary>\n        /// <param name=\"serialId\">要移除下载任务的序列编号。</param>\n        /// <returns>是否移除下载任务成功。</returns>\n        public bool RemoveDownload(int serialId)\n        {\n            return m_TaskPool.RemoveTask(serialId);\n        }\n\n        /// <summary>","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Download/DownloadManager.cs#L390-L426","documentation":"DownloadManager.AddDownload throws this when no download agent has been added yet (TotalAgentCount <= 0). Download agents are the workers that actually perform downloads; without at least one, no task can ever execute, so the manager fails fast. This is an initialization-order error, not a data error.","triggerScenarios":"Calling AddDownload before calling AddDownloadAgentHelper (e.g. in Awake before the download component has spawned its agents, or after accidentally removing all agent helpers).","commonSituations":"Game startup ordering issue where business code downloads before the Unity DownloadComponent initialized its agents; forgetting to attach a DownloadAgentHelper (e.g. UnityWebRequestDownloadAgentHelper) in the inspector; programmatic frameworks where AddDownloadAgentHelper was never called.","solutions":["Call AddDownloadAgentHelper with a concrete agent helper before any AddDownload call","If using UnityGameFramework, ensure the Download component exists and its agent helper count is >= 1 in the inspector","Move download calls after framework initialization (e.g. wait for the component's Awake/Start)"],"exampleFix":"// before\nint id = downloadManager.AddDownload(path, uri, null, 0, null); // no agent added yet\n// after\ndownloadManager.AddDownloadAgentHelper(new UnityWebRequestDownloadAgentHelper());\nint id = downloadManager.AddDownload(path, uri, null, 0, null);","handlingStrategy":"validation","validationCode":"if (downloadManager.TotalAgentCount <= 0) { downloadManager.AddDownloadAgentHelper(new UnityWebRequestDownloadAgentHelper()); }","typeGuard":"static bool HasDownloadAgents(DownloadManager dm) => dm.TotalAgentCount > 0;","tryCatchPattern":"try { int id = downloadManager.AddDownload(path, uri, null, 0, null); } catch (GameFrameworkException ex) when (ex.Message == \"You must add download agent first.\") { Log.Error(\"DownloadManager not initialized: no agents added\"); }","preventionTips":["Add download agent helpers during framework setup, before any gameplay code runs","Assert TotalAgentCount > 0 in a startup self-check","In Unity, verify the Download component's agent helper array is configured in the inspector"],"tags":["download","initialization-order","gameframework"],"backgroundTag":"invalid-state-transition","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}