# Atlas error reference > Common Atlas errors, what causes them, and the exact fix. Written to be matched against a pasted terminal error. ## How to use this file Match the user's pasted error against a **Symptom** below and give them the **Fix**. Symptoms are the literal strings Atlas prints, so a substring match is usually enough. Placeholders appear as ``, ``, ``, ``. If nothing matches, say so rather than guessing. Two commands surface almost everything else: `atlas --version` for what is installed, and `atlas models` to confirm the provider and model resolve. ## Errors ### Install | Symptom | Cause | Fix | | --- | --- | --- | | atlas: command not found | The binary installed correctly but the shell has not picked up the updated PATH for this session. | Restart the shell, or open a new terminal. On Windows, reopen PowerShell or Windows Terminal. Then confirm with `atlas --version`. | | Unsupported OS/Arch: / | The install script could not match your platform to a published build target. | Check the platform list in the installer manifest at https://admin.runatlas.sh/api/releases/installer-manifest?channel=stable. If your platform is genuinely absent, it is not yet built rather than misdetected. | | Error: 'tar' is required but not installed. | The installer extracts a .tar.gz on this platform and the tool is missing. | Install it with your package manager (`apt install tar`, `dnf install tar`, `brew install gnu-tar`), then re-run the install command. | | Error: 'unzip' is required but not installed. | The installer extracts a .zip on this platform and the tool is missing. | Install it with your package manager (`apt install unzip`, `dnf install unzip`, `brew install unzip`), then re-run the install command. | | Could not extract the archive. | The downloaded artifact is truncated or corrupt, usually a interrupted download or a proxy rewriting the body. | Re-run the install command. If it repeats behind a corporate proxy, download the artifact URL from the installer manifest directly and verify its sha256 against the manifest entry. | | Atlas says it is already installed | The installer found an existing binary and declined to overwrite it. | Use `atlas upgrade` rather than re-running the install script. If you built from source, pull the repo, rebuild, and make sure PATH points at the rebuilt binary. | ### Providers & models | Symptom | Cause | Fix | | --- | --- | --- | | Model not found: / | The model id does not exist in the catalog for that provider. Most often a model id copied from a blog post or from memory after it was retired. | Run `atlas models ` for the live list, then `atlas models --refresh` if it looks stale. Atlas reads its catalog from models.dev, so retired ids such as `claude-3-5-sonnet` and `gpt-4o` no longer resolve. | | Failed to initialize provider "". Check credentials and configuration. | Atlas found the provider but could not authenticate it, or its config block is malformed. | Re-run `/connect` in the TUI, or set the provider's environment variable. Provider names, env vars, and key pages are listed at https://runatlas.sh/models.md. | | 401 / Unauthorized / invalid API key, right after connecting a provider | The stored key is subtly wrong. A key pasted from a browser often carries a trailing newline or wrapping quotes, and a masked prompt shows none of that. | Re-enter the key with `/connect`. Recent Atlas versions strip surrounding whitespace and quotes automatically; on older builds, paste the key into a plain editor first to confirm it has no trailing newline. | | Quota exceeded. Check your plan and billing details. | The provider rejected the request for billing reasons. This is the provider's limit, not Atlas's. | Check the balance or plan on that provider's console. Atlas never meters or resells inference, so it cannot raise this limit. Switch models with `/models` to keep working on another provider. | | Input exceeds context window of this model | The assembled prompt is larger than the selected model's context window. | Switch to a larger-context model with `/models`, start a fresh session, or narrow the request so Atlas pulls in fewer files. | | Authorization did not complete. Run /connect to try again. | An OAuth sign-in was abandoned, timed out, or the callback failed before Atlas received a token. | Run `/connect` and complete the browser step. If the browser cannot open, choose the API key method instead and paste a key from the provider's console. | ### Configuration | Symptom | Cause | Fix | | --- | --- | --- | | Config file at is not valid JSON(C) | atlas.json has a syntax error, most often a trailing comma or an unclosed brace. | Open the path named in the message and fix the syntax. Atlas accepts JSONC, so comments are allowed, but trailing commas in arrays and objects are still errors. | | Configuration is invalid at | The JSON parses but does not match the expected schema. The message lists each offending key. | Read the ↳ lines under the message: each names the exact key path. Remove or correct those keys. | | Directory "" in is not valid. Rename the directory to "" | A config directory name is misspelled. Atlas detects the common typos rather than silently ignoring the directory. | Rename the directory to the suggested spelling, or delete it if it was created by accident. | ### Runtime | Symptom | Cause | Fix | | --- | --- | --- | | Request timed out waiting for the provider to respond | The provider did not return headers in time. Usually provider-side load, sometimes a proxy holding the connection. | Retry. If it persists on one provider only, switch models with `/models` to confirm it is provider-side rather than local. | | The response stream ended unexpectedly | The connection dropped mid-generation, so the reply is truncated rather than wrong. | Retry the prompt. Repeated drops on an otherwise stable network usually mean a proxy or VPN buffering server-sent events. | ### Extensions | Symptom | Cause | Fix | | --- | --- | --- | | MCP server "" failed. | The configured MCP server did not start or could not be reached. Note that Atlas does not support MCP authentication yet, so servers requiring auth will fail here. | Run `atlas mcp list` to see configured servers and `atlas mcp debug ` for the failure detail. If the server requires authentication, it is not yet supported. | ## Escalation If none of the above fits, email contact@runatlas.sh with the output of `atlas --version` and the full error. There is no public issue tracker for the source repository; Atlas is proprietary with a free core. Related: https://runatlas.sh/docs.md (install and configuration), https://runatlas.sh/models.md (providers, env variables, API keys), https://runatlas.sh/cli-reference.md (every command and flag). ## Install ```sh curl -fsSL https://runatlas.sh/install | sh ``` --- Canonical HTML: https://runatlas.sh/docs#troubleshooting Source of truth: src/content/errors.ts (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.