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 Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas with Hugging Face Inference in 2026: 51 Models Behind One HF_TOKEN
Atlas with Hugging Face Inference in 2026: 51 routed models behind one HF_TOKEN, GLM-4.7-Flash free at $0/$0 per Mtok, and the router margin on popular rows.
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: the 3.5M Token Context Model in 2026
Llama 4 Scout gives Atlas a 3.5M token context on Bedrock at $0.17 / $0.66 per Mtok, or $0.10 / $0.30 on DeepInfra. Setup, the portability trap, and when to switch.
Atlas with Gemma 2 27B (Ollama): the Free Local Diff Reviewer in 2026
Gemma 2 27B (Ollama) is Google's 2024 flagship open model, 16GB and Free (self-hosted), with 8K tokens (8,192) of context. Use it to review Atlas diffs, not write them.
Atlas with Mixtral 8x7B: Running the Original Sparse MoE in 2026
Mixtral 8x7B put sparse mixture-of-experts on the map in December 2023. In Atlas it gives 32,000 tokens at $0.70 / 1M input tokens. Setup, limits, and honest fit.
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: 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 GLM-4.5-Air: The 106B Self-Hostable Cheap Slot in 2026
GLM-4.5-Air drives Atlas at $0.20 per Mtok input and $1.10 per Mtok output on a 128K tokens (131,072) window. A 106B total / 12B active MIT-licensed MoE.