An editor talking to Atlas over ACP gets an auth_required JSON-RPC error with the message provider authentication required when Atlas has no credential for the provider the client asked for, so run `atlas auth login` for that provider and then restart the ACP session so the client re-initializes. In acp/error.ts, Atlas defines a tagged error per failure and toRequestError maps each one to the right JSON-RPC shape: AuthRequiredError becomes RequestError.authRequired, invalid model, mode, or effort become invalidParams, and an unsupported method becomes methodNotFound. Related ACP errors include model not found: <id>, mode not found: <mode>, and session not found: <id>.
Why does Atlas ACP return auth_required
Atlas ACP returns auth_required with the message provider authentication required when Atlas holds 0 credentials for the provider the editor asked for. In acp/error.ts, AuthRequiredError becomes RequestError.authRequired, so the JSON-RPC error is a deliberate signal to the client. Run `atlas auth login` for that provider.
ACP is how an editor drives Atlas as a coding agent from outside the terminal. When the editor requests work against a provider Atlas has never authenticated with, Atlas cannot make the model call, so it refuses at the protocol level with a shape the client is expected to understand. Run `atlas auth login` for the provider the ACP client is asking for. The credential lives with Atlas, not with the editor, so authenticating once through the Atlas CLI fixes every ACP client that talks to that Atlas installation.
How to fix model not found: <id> over Atlas ACP
model not found: <id> means the editor sent Atlas an ACP request naming a model that Atlas does not know. In acp/error.ts, an invalid model becomes invalidParams, so the JSON-RPC shape marks it as a bad request. Run `atlas models` to list the ids valid in 2026, then update the editor.
Model ids in Atlas are exact. Compare the id your editor plugin is sending with the ids `atlas models` prints, character for character, and fix the plugin's configuration to match. Atlas lets you switch the active model and provider on the fly with favorites and recents inside the TUI, so a model you can select interactively is one `atlas models` will list. A model that Atlas knows but has no credential for is a different error: that comes back as auth_required, not model not found.
What mode not found and effort errors mean in Atlas ACP
mode not found: <mode> and effort errors from Atlas ACP mean the editor is sending a value Atlas does not define. acp/error.ts maps all 3 invalid inputs, model, mode, and effort, to invalidParams, so the JSON-RPC response is telling the client its request was malformed rather than telling you to change Atlas.
For mode and effort errors, update the editor plugin. Atlas defines the set of valid modes and effort levels, and an ACP client sending something outside that set is out of date or misconfigured. Atlas drafts a plan in a read-only plan agent and asks before switching to a build agent, so modes are meaningful to how Atlas runs, not cosmetic labels a client can invent. The honest caveat: you cannot fix this from the Atlas side, because the wrong value originates in the client.
How to fix session not found: <id> over Atlas ACP
session not found: <id> from Atlas ACP means the editor referenced a session id Atlas no longer has. Because acp/error.ts defines 1 tagged error per failure, session not found is distinct from auth_required and from model not found, and it points at a stale client rather than a credential problem. Restart the ACP session.
Restart the ACP session after authenticating so the client re-initializes. An editor that cached a session id across an Atlas restart, or that kept an id after the session was ended, will keep sending an id that resolves to nothing. Re-initializing the ACP connection from the editor makes it request a fresh session. If session not found keeps appearing on every request, the editor plugin is not re-initializing at all, and the fix belongs in the plugin.
How to verify the ACP authentication fix worked
Verify the Atlas ACP fix by restarting the session after `atlas auth login` and re-running the editor's request, expecting 0 auth_required errors back. toRequestError in acp/error.ts maps AuthRequiredError to RequestError.authRequired, so the absence of that JSON-RPC error means Atlas found a credential for the provider the client requested.
Check the layers in order. Run `atlas auth login` for the provider, confirm the model id with `atlas models`, then restart the ACP session so the client re-initializes with the new credential. If a different error replaces auth_required, such as model not found: <id>, that is progress: Atlas got past authentication and is now rejecting the request parameters. Once the request succeeds, the editor drives Atlas normally, and every Atlas tool call is still permission-gated against allow, ask, and deny rules before it runs.
How to fix it
- 01Run `atlas auth login` for the provider the ACP client is asking for. AuthRequiredError becomes RequestError.authRequired, so auth_required always means a missing credential rather than a bad request.
- 02Confirm the model id the editor sends exists. Run `atlas models` to list valid ids, since an unknown id produces model not found: <id> as invalidParams.
- 03For mode not found: <mode> or effort errors, the editor is sending a value Atlas does not define, so update the editor plugin rather than changing Atlas config.
- 04Restart the ACP session after authenticating so the client re-initializes and picks up the new credential.
- 05Re-run the request from the editor and confirm no auth_required error is returned.
Frequently asked questions
- Why does my editor get auth_required from Atlas over ACP?
- Atlas has no credential for the provider the ACP client asked for. In acp/error.ts, AuthRequiredError becomes RequestError.authRequired. Run `atlas auth login` for that provider and restart the ACP session.
- What does provider authentication required mean in Atlas?
- provider authentication required is the message Atlas returns with the auth_required JSON-RPC error. It means Atlas cannot make the model call because the provider is not authenticated, not that the request was malformed.
- How do I fix model not found: <id> in Atlas ACP?
- Confirm the model id the editor sends exists. Run `atlas models` to list valid ids and update the editor plugin's configuration to match one of them exactly.
- Why does Atlas return mode not found: <mode> over ACP?
- The editor is sending a mode value Atlas does not define. Atlas maps invalid mode and effort values to invalidParams, so the fix is to update the editor plugin rather than to change Atlas configuration.
- Do I have to restart the ACP session after atlas auth login?
- Yes. Restart the ACP session after authenticating so the client re-initializes and picks up the new credential. An already-open session may keep failing with auth_required otherwise.
- What causes session not found: <id> in Atlas ACP?
- The editor referenced a session id Atlas no longer has, usually a stale id cached across a restart. Restart the ACP session so the client re-initializes and requests a fresh session.
- Does the editor or Atlas hold the provider credential?
- Atlas holds it. Running `atlas auth login` for the provider authenticates the Atlas installation, which fixes every ACP client talking to that installation, not just the one editor that hit the error.
Try SeaShell in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install SeaShellRelated guides
Atlas with Hugging Face Inference in 2026
Drive Atlas with Hugging Face Inference in 2026. Access 51 open-weights models, including free options and competitive pricing, through a single API for your AI coding agent.
Plan a Multi-File Change Before Editing with Atlas in 2026
How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.
Atlas with Llama 4 Scout in 2026
In 2026, Atlas leverages Llama 4 Scout for unparalleled long-context code understanding, offering 3.5M tokens on Bedrock at competitive pricing for deep repository analysis.
Atlas with Gemma 2 27B (Ollama) in 2026
Explore Atlas with Gemma 2 27B (Ollama), Google's 2024 flagship open model. Self-hosted and free, it offers strong reasoning and prose for Atlas's diff review, despite its 8K context limitation.
Atlas with Mixtral 8x7B in 2026
Explore Atlas with Mixtral 8x7B, the December 2023 sparse mixture-of-experts model. Understand its 32,000 token context, $0.70/Mtok pricing, and tradeoffs for coding agents in 2026.
Document a Module with a README Using Atlas (2026 Workflow)
How to document a module with a README using Atlas in 2026: the lsp tool's documentSymbol enumerates the real exports, read supplies the behavior, write emits the README.
Atlas with Qwen3 14B in 2026: A Developer's Guide
Evaluate Atlas with Qwen3 14B for your coding agent in 2026. This 14B model offers reasoning capabilities, a 128K token context, and reliable tool use at $0.35/Mtok input.
Atlas with GLM-4.5-Air in 2026
Explore GLM-4.5-Air's cost-effective performance with Atlas in 2026. This 12B active parameter model offers a 128K token context window for $0.20/Mtok input.