Atlas task fails with Unknown agent type: <name> 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.
Why does Atlas say Unknown agent type is not a valid agent type
Atlas says Unknown agent type: <name> 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: <name> 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: <name> 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.
How to fix it
- 01Run `atlas agent` to list registered agents and their modes.
- 02Pass a subagent, not a primary agent: build and plan are primary and cannot be launched as tasks.
- 03If you defined a custom agent in markdown, confirm its frontmatter sets mode: subagent.
- 04Note the plan agent explicitly denies task: { general: "deny" }, so in plan mode the general subagent is unavailable by design.
Frequently asked questions
- 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: <name> 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.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas for Django in 2026
Atlas, the terminal-native AI coding agent, empowers Django developers in 2026. Boost productivity across models, views, and migrations with secure, reviewable AI assistance.
Atlas with Code Llama (local via Ollama): a Fill-in-the-Middle Baseline in 2026
Code Llama runs free and local via Ollama at 7b, 13b, 34b, and 70b with a 16,384 token context. Strong at infilling, but too small and too old for Atlas agent work.
Atlas for Bun: Terminal-Native AI Coding in 2026
Atlas is a terminal-native AI coding agent for Bun. Swap Node compatibility shims for Bun.serve and bun:sqlite, iterate with bun test, and format with bun fmt in 2026.
Atlas with Qwen3.6 Max Preview: The Top 3.6 Tier, Reviewed in 2026
Qwen3.6 Max Preview is Alibaba's top Qwen3.6 tier at $1.30 per Mtok input and $7.80 per Mtok output, with 256K tokens (262,144) of context. What it is worth inside Atlas.
Atlas with Llama 3.2 1B (local via Ollama): the 2026 offline small_model slot
Llama 3.2 1B (local via Ollama) in Atlas: a 1.3GB CPU-friendly pull with a 128,000 token window, Free (self-hosted), best wired to small_model, not model.
Atlas with Gemini 3.1 Pro: Setup, Cost, and Tradeoffs in 2026
Run Atlas on Gemini 3.1 Pro in 2026: a 1,048,576 token window at $2 / $12 per Mtok, with real setup steps, the 65,536 output ceiling, and when to switch models.
Atlas for Fortran: fpm.toml, Explicit Interfaces, and fprettify in 2026
Atlas is a terminal-native AI coding agent for Fortran in 2026. It reads modules, explicit interfaces, and intent declarations, runs fpm test behind a prompt, and runs fprettify.
Atlas with Mistral Medium 3 (2505) in 2026: Symmetric Limits, $0.40 In
Mistral Medium 3 (2505) runs Atlas with symmetric 131,072 token context and output at $0.40 / 1M input tokens and $2.00 / 1M output tokens. Setup, limits, successors.