# Atlas error: default agent "" not found, is a subagent, or is hidden > 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. Atlas startup fails with default agent "" not found, default agent "" is a subagent, default agent "" 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. ## Symptom Atlas startup fails with one of four messages: default agent "" not found; default agent "" is a subagent; default agent "" is hidden; or no primary visible agent found. ## Cause Agent.state validates `default_agent` from config against the resolved agent map. A subagent, like general or explore, and a hidden agent are both rejected as defaults, and Atlas refuses to start with no visible primary agent at all rather than picking one arbitrarily. ## Fix 1. Set `default_agent` to a primary agent such as build or plan. 2. Run `atlas agent` to see which agents are registered and which mode each one has. 3. If you defined a custom agent in markdown, ensure its frontmatter sets mode: primary and does not set hidden: true. 4. Remove `default_agent` entirely to fall back to the built-in build agent. 5. Restart Atlas and confirm startup completes with no default agent error. ## Why does Atlas say default agent "" not found? Atlas says default agent "" 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 "" 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 "" is hidden? Atlas says default agent "" 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 "" 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. ## FAQ ### 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. ### 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. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/default-agent-not-found Source of truth: aeo_pages row `/resources/troubleshooting/default-agent-not-found` (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.