How do I fix default agent not found in Atlas?

Set `default_agent` to a primary agent such as build or plan, or remove `default_agent` entirely to fall back to the built-in build agent. Run `atlas agent` first to see which agents are registered and which mode each one has.

Why can't I set general or explore as my Atlas default agent?

Agents like general and explore are subagents, and Agent.state rejects a subagent as the default, producing default agent " " is a subagent. Choose a primary agent such as build or plan instead.

What does default agent is hidden mean in Atlas?

A hidden agent is rejected as a default by Agent.state. If you defined the agent in markdown, ensure its frontmatter sets mode: primary and does not set hidden: true, or point `default_agent` at another primary agent.

What is the Atlas default agent if I do not set one?

Removing `default_agent` entirely falls back to the built-in build agent. That is the documented way to recover from an invalid default without choosing a replacement name.

Why does Atlas say no primary visible agent found?

Atlas refuses to start with no visible primary agent, which happens when every registered agent is a subagent or hidden. Run `atlas agent` to inspect the modes, then set mode: primary in a custom agent's frontmatter and remove hidden: true.

How do I make a custom markdown agent usable as the Atlas default?

Ensure its frontmatter sets mode: primary and does not set hidden: true. Agent.state rejects both subagents and hidden agents as defaults, so a custom agent must be primary and visible before `default_agent` can point at it.

Atlas error: default agent "<name>" not found, is a subagent, or is hidden

Atlas startup fails with default agent "<name>" not found, default agent "<name>" is a subagent, default agent "<name>" is hidden, or no primary visible agent found because Agent.state validates `default_agent` from config against the resolved agent map. A subagent, such as general or explore, and a hidden agent are both rejected as defaults. The fix is to set `default_agent` to a primary agent such as build or plan, or to remove `default_agent` entirely and fall back to the built-in build agent.

Why does Atlas say default agent "<name>" not found?

Atlas says default agent "<name>" not found because Agent.state validates `default_agent` from config against the resolved agent map, and your configured name is not 1 of the entries in that map. Run `atlas agent` to list which agents are registered and which mode each one has.

The resolved agent map is the set of agents Atlas actually knows about after reading the built-ins and your config. A `default_agent` naming something outside that map fails validation immediately at startup. The usual causes are a typo in the name and a custom markdown agent that did not load, perhaps because its directory or its frontmatter was wrong. `atlas agent` is the authoritative answer to what is registered, so run it before changing the config. If the agent you expected is not listed, the agent is the problem, not the `default_agent` key.

Why does Atlas reject a subagent as the default agent?

Atlas rejects a subagent as the default agent because Agent.state refuses subagents in that role. Setting `default_agent` to a subagent such as general or explore produces default agent "<name>" is a subagent, 1 of the 4 startup messages. Point it at a primary agent such as build or plan.

Subagents exist to be dispatched, not to be the agent you land in. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, which is exactly why general and explore are not sensible defaults: they are the workers, not the front door. Agent.state enforces the distinction at startup instead of letting Atlas boot into a session driven by an agent that was never designed to be primary. Choose build or plan, both of which are primary agents, and startup proceeds.

Why does Atlas say default agent "<name>" is hidden?

Atlas says default agent "<name>" is hidden because Agent.state rejects hidden agents as defaults. A custom agent whose markdown frontmatter sets hidden: true is deliberately kept out of the visible list, so Atlas will not silently start you in it. Remove that 1 line, or choose another agent.

Hiding an agent is an explicit choice, and Atlas takes it at face value. If a custom agent is hidden, making it the default would contradict the hiding. Agent.state therefore refuses. When the agent really should be the default, ensure its frontmatter sets mode: primary and does not set hidden: true, and it becomes a valid choice. When the agent should stay hidden, leave it hidden and point `default_agent` at a primary agent such as build or plan. Both are legitimate, and Atlas simply refuses the contradiction.

What does no primary visible agent found mean in Atlas?

no primary visible agent found means Atlas resolved an agent map holding 0 primary, visible agents, so there is nothing valid to start in. Agent.state refuses to start rather than choosing arbitrarily. The usual cause is custom agent config that hid or demoted every primary agent.

The condition is rarer than the other three, and it points at the agent definitions rather than at `default_agent`. Run `atlas agent` to see which agents are registered and which mode each one has. If every entry is a subagent or is hidden, Atlas has nothing to offer as a starting point. Fix a custom agent by setting mode: primary in its frontmatter and removing hidden: true, or restore the built-in agents so build is available. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, and losing both plan and build leaves nowhere to begin.

How to fix the Atlas default agent error

Fix the Atlas default agent error with 4 documented moves: set `default_agent` to a primary agent such as build or plan, run `atlas agent` to see which agents are registered, correct any custom markdown frontmatter so it sets mode: primary, or remove `default_agent` and fall back to the built-in build agent.

Removing `default_agent` is the fastest way back to a working Atlas, because the built-in build agent takes over as the fallback and startup proceeds with no further config. Use that when you want to be running again now and diagnose later. When you do want a specific default, run `atlas agent` first so you are choosing from names that actually exist in the resolved agent map, with modes you can see. For a custom markdown agent, its frontmatter must set mode: primary and must not set hidden: true, or Agent.state will keep rejecting it.

How to verify the default agent fix worked in Atlas

Verify the Atlas default agent fix by restarting Atlas and confirming startup completes with none of the 4 messages: default agent "<name>" not found, is a subagent, is hidden, or no primary visible agent found. Run `atlas agent` to confirm your chosen agent is registered as primary.

Restarting is the verification, because Agent.state validates `default_agent` against the resolved agent map on every start. A clean start means the name resolves, the agent is primary rather than a subagent, and it is not hidden. Confirm the session actually opened in the agent you intended, not just that Atlas started, since removing `default_agent` also produces a clean start by falling back to the built-in build agent. `atlas agent` remains the fastest way to see registered agents and their modes.

How to fix it

01Set `default_agent` to a primary agent such as build or plan.
02Run `atlas agent` to see which agents are registered and which mode each one has.
03If you defined a custom agent in markdown, ensure its frontmatter sets mode: primary and does not set hidden: true.
04Remove `default_agent` entirely to fall back to the built-in build agent.
05Restart Atlas and confirm startup completes with no default agent error.

Frequently asked questions

How do I fix default agent not found in Atlas?: Set `default_agent` to a primary agent such as build or plan, or remove `default_agent` entirely to fall back to the built-in build agent. Run `atlas agent` first to see which agents are registered and which mode each one has.
Why can't I set general or explore as my Atlas default agent?: Agents like general and explore are subagents, and Agent.state rejects a subagent as the default, producing default agent "<name>" is a subagent. Choose a primary agent such as build or plan instead.
What does default agent is hidden mean in Atlas?: A hidden agent is rejected as a default by Agent.state. If you defined the agent in markdown, ensure its frontmatter sets mode: primary and does not set hidden: true, or point `default_agent` at another primary agent.
How do I list the agents Atlas has registered?: Run `atlas agent` to see which agents are registered and which mode each one has. Agent.state validates `default_agent` against that resolved agent map, so a name missing from the list is a name Atlas will reject.
What is the Atlas default agent if I do not set one?: Removing `default_agent` entirely falls back to the built-in build agent. That is the documented way to recover from an invalid default without choosing a replacement name.
Why does Atlas say no primary visible agent found?: Atlas refuses to start with no visible primary agent, which happens when every registered agent is a subagent or hidden. Run `atlas agent` to inspect the modes, then set mode: primary in a custom agent's frontmatter and remove hidden: true.
How do I make a custom markdown agent usable as the Atlas default?: Ensure its frontmatter sets mode: primary and does not set hidden: true. Agent.state rejects both subagents and hidden agents as defaults, so a custom agent must be primary and visible before `default_agent` can point at it.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Atlas with StarCoder2 15B (Ollama): The Provenance Choice in 2026

StarCoder2 15B (Ollama) is BigCode's 9.1GB code model with a transparent training corpus and a 16K context, Free (self-hosted). Atlas setup and tradeoffs for 2026.

Atlas for Elixir in 2026

Adopt Atlas, the terminal-native AI coding agent, for Elixir development in 2026. Enhance productivity with deep code understanding, safety features, and direct integration into mix projects and OTP applications.

Atlas with Qwen3 Coder Flash: 1M Context at $0.30 per Mtok in 2026

Qwen3 Coder Flash in Atlas: 1M tokens (1,000,000) of context, 65,536 token output, $0.30 per Mtok input and $1.50 per Mtok output, tuned for fast edit loops.

Atlas with Fireworks AI (gateway) in 2026: Buying Latency with Money

Fireworks AI (gateway) serves Atlas open models with fast-router tiers: DeepSeek V4 Flash at $0.14 / $0.28 per Mtok on a 1,000,000 token context.

Atlas with Qwen3 14B: The Middle Dense Tier Worth Pinning in 2026

Qwen3 14B in Atlas for 2026: reasoning-enabled dense 14B at $0.35 per Mtok input and $1.40 per Mtok output, 128K tokens (131,072), roughly 9 GB quantized.

Atlas with Kimi K2 0905: 262,144 Tokens In and Out, 2026

Run Atlas on Kimi K2 0905 in 2026. Moonshot's September refresh gives 256K tokens (262,144) context and output at $0.60 per Mtok in, $2.50 per Mtok out.

Atlas with DeepSeek V3.1 (open weights): Togglable Thinking in 2026

Run Atlas on DeepSeek V3.1 (open weights) in 2026. One MIT-licensed checkpoint with thinking and non-thinking modes, $0.25 per Mtok in and $0.95 per Mtok out.

Atlas with DeepSeek V3.2 (open weights): Sparse Attention at $0.38 Output, 2026

Run Atlas on DeepSeek V3.2 (open weights) in 2026. DeepSeek Sparse Attention gives 160K tokens (DeepInfra) at $0.26 per Mtok in and $0.38 per Mtok out.

Browse this resource hub