# Atlas error: Unknown agent type is not a valid agent type > Run `atlas agent` to list registered agents and their modes, then pass a subagent: only agents with mode subagent, such as general and explore, can be launched by the task tool. Atlas task fails with Unknown agent type: is not a valid agent type because TaskTool resolves subagent_type against the registered agent map and fails when there is no match. Only agents with mode subagent, for example general and explore, can be launched this way. The fix is to run `atlas agent` to list registered agents and their modes, then pass a subagent rather than a primary agent, since build and plan are primary and cannot be launched as tasks. ## Symptom The task tool fails with: Unknown agent type: is not a valid agent type. The subagent never starts and no child session appears. ## Cause TaskTool resolves subagent_type against the registered agent map and fails when there is no match. Only agents with mode subagent, for example general and explore, can be launched this way. ## Fix 1. Run `atlas agent` to list registered agents and their modes. 2. Pass a subagent, not a primary agent: build and plan are primary and cannot be launched as tasks. 3. If you defined a custom agent in markdown, confirm its frontmatter sets mode: subagent. 4. Note the plan agent explicitly denies task: { general: "deny" }, so in plan mode the general subagent is unavailable by design. ## Why does Atlas say Unknown agent type is not a valid agent type Atlas says Unknown agent type: is not a valid agent type because TaskTool resolves subagent_type against the registered agent map and fails when there is no match. In the 2026 build, only agents with mode subagent, for example general and explore, can be launched by the task tool. The registered agent map is the single source of truth for what the task tool will accept. TaskTool takes the subagent_type you passed, looks it up, and refuses the call outright when nothing matches. Two mistakes account for nearly every occurrence. The first is a name that is simply not registered, usually a typo or an agent from another tool's vocabulary. The second is a name that exists but is a primary agent rather than a subagent, which the map records with a different mode. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, and only mode subagent agents are eligible for that fan-out. ## How to list the agents Atlas will accept for a task Run `atlas agent` to list registered agents and their modes. That listing is the authoritative answer to Unknown agent type: is not a valid agent type, because TaskTool resolves subagent_type against exactly 1 map, the registered agent map, before it launches anything. Read two columns in the output: the agent name and its mode. Any agent whose mode is subagent, such as general and explore, is a legal value for subagent_type. Anything else is not, no matter how sensible the name sounds. Copy the name verbatim from the listing rather than typing it from memory, since the lookup is an exact match. If the agent you expected to see is missing entirely, it was never registered, and the fix is registration, not a different spelling of the name in the task call. ## Why can I not launch the build or plan agent as an Atlas task Atlas build and plan are primary agents, and those 2 cannot be launched as tasks. Passing either one as subagent_type produces Unknown agent type: is not a valid agent type, because TaskTool only resolves agents whose mode is subagent, for example general and explore. The primary agents are the ones you drive directly in a session, not ones you fan out to. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, which is a session-level transition rather than a task launch. Trying to spawn build from inside a task call would sidestep that approval boundary, so the agent map simply does not offer it. When you want parallel work, choose a subagent from the `atlas agent` listing. When you want to change how the current session behaves, switch the primary agent instead of launching a task. ## How to make a custom Atlas agent launchable as a subagent If you defined a custom Atlas agent in markdown, confirm its frontmatter sets mode: subagent. That 1 line is what makes the agent resolvable. Without it, TaskTool will not match the name against the registered agent map, and the call fails with Unknown agent type even though the file exists. The frontmatter mode field is what makes a custom agent eligible for the task tool. Set mode: subagent in the markdown definition, then re-run `atlas agent` and confirm the agent now appears with that mode in the listing. If it appears but the mode is wrong, the frontmatter did not parse the way you expected. If it does not appear at all, Atlas is not picking the file up from the location you put it in, and no change to the task call will help until the agent is actually registered. ## Why is the general subagent unavailable in Atlas plan mode In Atlas plan mode the general subagent is unavailable by design, because the plan agent explicitly denies it with task: { general: "deny" }. That is 1 deliberate deny rule, not a missing registration, so launching general from plan mode is blocked rather than unresolvable. Plan is a read-only agent, and Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent. Allowing the plan agent to spawn a general subagent would let planning quietly perform work through a child session, so the deny rule closes that door. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, and task: { general: "deny" } is exactly such a rule. If you need general, switch out of plan mode first. If you need to explore while planning, use a subagent that plan mode still permits. ## FAQ ### how to fix Unknown agent type is not a valid agent type in Atlas Run `atlas agent` to list registered agents and their modes, then pass a subagent as subagent_type. TaskTool only resolves agents whose mode is subagent, for example general and explore. ### which subagent types can the Atlas task tool launch Only agents with mode subagent, for example general and explore. Run `atlas agent` to see the full registered list and each agent's mode. ### can I launch the Atlas build agent with the task tool No. build and plan are primary agents and cannot be launched as tasks. Passing either as subagent_type produces Unknown agent type: is not a valid agent type. ### why does my custom Atlas agent fail as an unknown agent type Its frontmatter is probably missing mode: subagent. TaskTool resolves subagent_type against the registered agent map, and an agent without mode subagent is not eligible. ### why can I not use the general subagent in Atlas plan mode The plan agent explicitly denies task: { general: "deny" }, so in plan mode the general subagent is unavailable by design. Switch out of plan mode to use it. ### how do I see the mode of an Atlas agent Run `atlas agent`. The listing shows each registered agent along with its mode, which is what TaskTool checks before launching a subagent. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/task-unknown-agent-type Source of truth: aeo_pages row `/resources/troubleshooting/task-unknown-agent-type` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.