EllanJiang/GameFramework · error · GameFrameworkException

You must add download agent first.

Error message

You must add download agent first.

What it means

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.

Solutions

1. Call AddDownloadAgentHelper with a concrete agent helper before any AddDownload call
2. If using UnityGameFramework, ensure the Download component exists and its agent helper count is >= 1 in the inspector
3. Move download calls after framework initialization (e.g. wait for the component's Awake/Start)

Example fix

// before
int id = downloadManager.AddDownload(path, uri, null, 0, null); // no agent added yet
// after
downloadManager.AddDownloadAgentHelper(new UnityWebRequestDownloadAgentHelper());
int id = downloadManager.AddDownload(path, uri, null, 0, null);

if (downloadManager.TotalAgentCount <= 0) { downloadManager.AddDownloadAgentHelper(new UnityWebRequestDownloadAgentHelper()); }

static bool HasDownloadAgents(DownloadManager dm) => dm.TotalAgentCount > 0;

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"); }

When it happens

Trigger: Calling AddDownload before calling AddDownloadAgentHelper (e.g. in Awake before the download component has spawned its agents, or after accidentally removing all agent helpers).

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• You must set resource manager first.
• Offset is invalid.
• Length is invalid.
• Delta length is invalid.
• Download agent helper is invalid.

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

Appendix: source

Thrown at GameFramework/Download/DownloadManager.cs:408

        /// <param name="tag">下载任务的标签。</param>
        /// <param name="priority">下载任务的优先级。</param>
        /// <param name="userData">用户自定义数据。</param>
        /// <returns>新增下载任务的序列编号。</returns>
        public int AddDownload(string downloadPath, string downloadUri, string tag, int priority, object userData)
        {
            if (string.IsNullOrEmpty(downloadPath))
            {
                throw new GameFrameworkException("Download path is invalid.");
            }

            if (string.IsNullOrEmpty(downloadUri))
            {
                throw new GameFrameworkException("Download uri is invalid.");
            }

            if (TotalAgentCount <= 0)
            {
                throw new GameFrameworkException("You must add download agent first.");
            }

            DownloadTask downloadTask = DownloadTask.Create(downloadPath, downloadUri, tag, priority, m_FlushSize, m_Timeout, userData);
            m_TaskPool.AddTask(downloadTask);
            return downloadTask.SerialId;
        }

        /// <summary>
        /// 根据下载任务的序列编号移除下载任务。
        /// </summary>
        /// <param name="serialId">要移除下载任务的序列编号。</param>
        /// <returns>是否移除下载任务成功。</returns>
        public bool RemoveDownload(int serialId)
        {
            return m_TaskPool.RemoveTask(serialId);
        }

        /// <summary>

View on GitHub (pinned to d0c010b051)