EllanJiang/GameFramework · error · GameFrameworkException

Task agent is invalid.

Error message

Task agent is invalid.

What it means

TaskPool.AddAgent validates that the ITaskAgent<T> being registered is not null before pushing it onto the free-agent stack. A null agent would corrupt the pool's agent stacks and fail later during Update, so the pool fails fast at registration.

Solutions

1. Ensure the agent instance is created before calling AddAgent (new YourAgent(...) or GetComponent) and assert it is non-null
2. Check your agent factory/provider for silent null returns
3. Guard the call site: only AddAgent after successful initialization

Example fix

// before
m_TaskPool.AddAgent(m_Agent); // m_Agent is null
// after
Debug.Assert(m_Agent != null, "Task agent not initialized");
if (m_Agent != null) m_TaskPool.AddAgent(m_Agent);

if (agent == null) throw new ArgumentNullException(nameof(agent));
m_TaskPool.AddAgent(agent);

bool CanAdd(ITaskAgent<MyTask> agent) => agent != null;

try { taskPool.AddAgent(agent); }
catch (GameFrameworkException ex) { Debug.LogError($"Agent registration failed: {ex.Message}"); }

When it happens

Trigger: Calling taskPool.AddAgent(null), typically when a helper/agent factory returned null (e.g. a custom ITaskAgent property never assigned, or GetComponent returned null in Unity).

Common situations: Setting up a download/websocket/asset task agent whose field wasn't initialized; refactoring where agent construction was moved behind a loader that hadn't run yet.

Related errors

• Results is invalid.
• Download agent helper is invalid.
• Task is invalid.
• Load resource agent helper is invalid.
• Resource helper is invalid.

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

Appendix: source

Thrown at GameFramework/Base/TaskPool/TaskPool.cs:130

        public void Shutdown()
        {
            RemoveAllTasks();

            while (FreeAgentCount > 0)
            {
                m_FreeAgents.Pop().Shutdown();
            }
        }

        /// <summary>
        /// 增加任务代理。
        /// </summary>
        /// <param name="agent">要增加的任务代理。</param>
        public void AddAgent(ITaskAgent<T> agent)
        {
            if (agent == null)
            {
                throw new GameFrameworkException("Task agent is invalid.");
            }

            agent.Initialize();
            m_FreeAgents.Push(agent);
        }

        /// <summary>
        /// 根据任务的序列编号获取任务的信息。
        /// </summary>
        /// <param name="serialId">要获取信息的任务的序列编号。</param>
        /// <returns>任务的信息。</returns>
        public TaskInfo GetTaskInfo(int serialId)
        {
            foreach (ITaskAgent<T> workingAgent in m_WorkingAgents)
            {
                T workingTask = workingAgent.Task;
                if (workingTask.SerialId == serialId)
                {

View on GitHub (pinned to d0c010b051)