EllanJiang/GameFramework · error · GameFrameworkException

You must add web request agent first.

Error message

You must add web request agent first.

What it means

WebRequestManager.AddWebRequest throws GameFrameworkException with 'You must add web request agent first.' when a request is submitted while TotalAgentCount <= 0, i.e. no web request agent (and thus no helper) has been registered with the manager. The manager has no worker to process the task, so it refuses to enqueue it.

Solutions

1. Register at least one agent before any request: call m_WebRequestManager.AddAgent(typeof(UnityWebRequestAgentHelper)) (or let WebRequestComponent initialize it) prior to AddWebRequest.
2. Defer request-issuing code until after manager initialization (e.g. subscribe to a Start/Ready event).
3. Guard with a check: if (m_WebRequestManager.TotalAgentCount <= 0) initialize agents before submitting tasks.

Example fix

// before
public void Awake()
{
    m_WebRequestManager.AddWebRequest(url); // no agent yet
}
// after
public void Start()
{
    if (m_WebRequestManager.TotalAgentCount <= 0)
    {
        m_WebRequestManager.AddAgent(typeof(UnityWebRequestAgentHelper), 1);
    }
    m_WebRequestManager.AddWebRequest(url);
}

if (m_WebRequestManager.TotalAgentCount <= 0)
{
    m_WebRequestManager.AddAgent(typeof(UnityWebRequestAgentHelper), 1);
}
int serialId = m_WebRequestManager.AddWebRequest(webRequestUri);

try
{
    int serialId = m_WebRequestManager.AddWebRequest(webRequestUri);
}
catch (GameFrameworkException ex) when (ex.Message == "You must add web request agent first.")
{
    Log.Error("WebRequestManager not initialized: call AddAgent before AddWebRequest.");
}

When it happens

Trigger: Calling AddWebRequest before calling AddAgent (e.g. before the WebRequestComponent's Ready/agent setup runs, or in code executing during scene load before initialization).

Common situations: Game logic issues requests in Awake/OnEnable before the WebRequestComponent initializes agents; the agent-registration code was removed or gated behind a failed condition; a wrapper manager calls AddWebRequest before its own Init.

Related errors

• You must set resource manager first.
• Web request agent helper is invalid.
• Task is invalid.
• Web request uri is invalid.
• Owner is invalid.

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

Appendix: source

Thrown at GameFramework/WebRequest/WebRequestManager.cs:416

        /// <summary>
        /// 增加 Web 请求任务。
        /// </summary>
        /// <param name="webRequestUri">Web 请求地址。</param>
        /// <param name="postData">要发送的数据流。</param>
        /// <param name="tag">Web 请求任务的标签。</param>
        /// <param name="priority">Web 请求任务的优先级。</param>
        /// <param name="userData">用户自定义数据。</param>
        /// <returns>新增 Web 请求任务的序列编号。</returns>
        public int AddWebRequest(string webRequestUri, byte[] postData, string tag, int priority, object userData)
        {
            if (string.IsNullOrEmpty(webRequestUri))
            {
                throw new GameFrameworkException("Web request uri is invalid.");
            }

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

            WebRequestTask webRequestTask = WebRequestTask.Create(webRequestUri, postData, tag, priority, m_Timeout, userData);
            m_TaskPool.AddTask(webRequestTask);
            return webRequestTask.SerialId;
        }

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

        /// <summary>

View on GitHub (pinned to d0c010b051)