Resource hub
Troubleshooting and errors
Diagnose and fix Atlas errors: authentication, MCP servers, model providers, permissions, git, and tool failures.
Atlas error: MCP server failed to connect
Fix the Atlas MCP server "failed" status. Run atlas mcp to read the status row, test the server's command or url by hand, then raise timeout and restart.
Atlas: MCP Authentication Required, server needs_auth
Atlas shows "MCP Authentication Required" and status needs_auth. Run atlas mcp auth <name>, finish the browser consent, then re-run atlas mcp to confirm connected.
Atlas ProcessRunFailedError: Command failed with code <n>: <cmd>
Atlas raises ProcessRunFailedError when a spawned command exits non-zero. Read the stderr appended to the message, re-run the command in the same cwd, check the code.
Atlas update fails with "checksum mismatch; aborting" or a failed release download
Atlas compares the SHA-256 of a downloaded release against artifact.sha256 and aborts on any mismatch. Re-run the update, and check for a proxy that rewrites binaries.
Atlas bash tool: "Failed to parse command" and how to fix it
Atlas bash fails with Failed to parse command when the shell tool cannot build a syntax tree. Fix unbalanced quotes or heredocs, split compound commands, or use a script file.
Atlas glob: "Results are truncated: showing first 100 results"
Atlas glob stops at 100 results and says Consider using a more specific path or pattern. Narrow the pattern, scope `path` to a subdirectory, or use grep to search contents.
Atlas bash tool: "shell tool terminated command after exceeding timeout <n> ms"
Atlas bash reports shell tool terminated command after exceeding timeout <n> ms. Retry with a larger timeout in milliseconds, or check whether the command is waiting on input.
Atlas edit error: Could not find oldString in the file
Atlas edit fails when all nine replacers miss your oldString. Re-read the file with the read tool and copy oldString verbatim out of the output, whitespace included.
Atlas WorktreeNotGitError: worktree operations fail outside a git repo
Atlas raises WorktreeNotGitError when the project directory is not a git repository. Run `git status` inside it, initialize the repo, then retry the worktree operation.
Atlas edit error: No changes to apply, oldString and newString are identical
Atlas edit fails fast when oldString and newString are identical, because a no-op edit is always an error. Change newString so it actually differs from oldString.
Atlas TUI error: Failed to fork session
Atlas shows a red Failed to fork session toast when the source session is gone or busy. Confirm it exists with atlas session, wait out SessionBusyError, retry the fork.
Atlas GitHub Action fails: Environment variable "MODEL" is not set
Fix Atlas GitHub Action errors such as Environment variable "MODEL" is not set and Invalid model. Set MODEL to provider/model, supply PROMPT, grant write access.
atlas upgrade failed: please run the terminal as Administrator and try again
atlas upgrade stops with "Upgrade failed" when choco is not running from an elevated command shell. Reopen the terminal as Administrator and re-run atlas upgrade.
Atlas error: Compaction parent must be a user message
Atlas refuses to compact a session when the parentID resolves to an assistant message. Anchor compaction on a user message id, or let Atlas pick the parent.
Atlas webfetch error: Response too large (exceeds 5MB limit)
Atlas webfetch fails with Response too large (exceeds 5MB limit) when a page exceeds MAX_RESPONSE_SIZE. Fetch a narrower URL, request text or markdown format.
Atlas error: the server returned a login page instead of JSON when loading remote config
Atlas fails at startup when a remote config URL returns an SSO login page instead of JSON. Run atlas auth login <url> to re-authenticate, or inline the config locally.
atlas run cannot read interactive input: how to fix INTERACTIVE_INPUT_ERROR
atlas run fails with INTERACTIVE_INPUT_ERROR when it has no TTY. Pipe the prompt in on stdin or pass it as an argument, and supply the model explicitly in CI.
Atlas MCP error: Connection closed mid-session
An Atlas MCP server flips to failed with "Connection closed" when its transport drops. Check the server process, look for idle timeouts, raise timeout, reconnect.
Atlas error: Resource not found: <client>/<uri>
Atlas fails to attach an MCP resource with "Resource not found". Run atlas mcp to check the client is connected, re-list resources, verify the URI, then reconnect.
Atlas IDE extension install failed: Unknown IDE and InstallFailedError
Atlas raises "Unknown IDE" or InstallFailedError when installing its IDE extension. Run the install from a supported IDE's integrated terminal with its CLI on PATH.
Atlas image errors: Image could not be decoded, Image URL must be a base64 data URL, Image resizer is unavailable
Atlas models four image failures. Fix them by resizing the image, passing a base64 data URL, re-exporting as PNG or JPEG, or pre-shrinking when the resizer is missing.
Atlas error: No LSP server available for this file type
Atlas lsp fails with No LSP server available for this file type when no client matches the extension. Install the language server, put it on PATH, then retry.
Atlas VcsPatchApplyError: patch cannot be applied because the tree is not clean
Atlas fails with VcsPatchApplyError reason "not-clean" when the working tree has uncommitted changes. Commit or stash them, then apply the patch again.
Atlas error: Configuration is invalid, Unrecognized key in config
Atlas exits with Configuration is invalid at <path> and an Unrecognized key issue. Remove or rename the key, check casing, and nest provider or mcp entries correctly.
Atlas TUI error: Unrecognized keybind in config
The Atlas TUI refuses to start with Unrecognized keybind: <name>. Fix the action name against the Definitions map in Atlas-Frontend/tui/src/config/keybind.ts and restart.
Atlas error: Config file at <path> is not valid JSON(C)
Atlas exits with Config file at <path> is not valid JSON(C) and a caret pointing at the bad character. Fix the line and column named in the JSONC error dump, then re-run Atlas.
Atlas error: No providers configured (ProviderNoProvidersError)
Atlas fails with ProviderNoProvidersError when zero providers autoload. Fix it by running atlas auth login to add one credential, then confirming with atlas providers.
Atlas grep tool: "pattern is required" and how to fix it
Atlas grep fails with pattern is required when the pattern parameter is empty. Supply a non-empty regex pattern, and use `include` and `path` to scope the search.
Atlas: Server does not support dynamic client registration
Atlas status needs_client_registration means the MCP server rejects dynamic registration. Register an OAuth client yourself, set oauth clientId in config, restart, re-auth.
Atlas error: Failed to toggle MCP and Failed to refresh MCP status: no data returned
Atlas logs Failed to toggle MCP when the server API call throws or returns no data. Confirm the Atlas server is running, re-open the MCP dialog, check the config entry.
Atlas error: Quota exceeded. Check your plan and billing details.
Atlas maps insufficient_quota to a non-retryable error and stops. Check the provider billing dashboard, look for an org spend cap, and switch provider with atlas models.
Atlas error "Response decompression failed" (ZlibError): how to fix it
Atlas reports "Response decompression failed" with code ZlibError when a gzip/deflate body cannot be inflated. Retry, then bypass any proxy for the provider host.
Atlas error: Plugin directory <path> is missing package.json or index file
Atlas fails to load a path-based plugin when the directory has no package.json or index file. Add a package.json with a main or exports entry, then restart Atlas.
Atlas worktree removal requires force because it is dirty
Atlas raises Git.WorktreeError with forceRequired true when a worktree contains modified or untracked files. Commit or stash inside the worktree, then remove it.
Atlas error: Unknown agent type is not a valid agent type
Atlas task fails with Unknown agent type: <name> is not a valid agent type. Run atlas agent to list registered agents and pass a subagent, not build or plan.
Atlas NpmInstallFailedError: npm install failed while adding a package
Atlas raises NpmInstallFailedError with the packages it tried to add and the directory it ran in. Check registry access, then run the install by hand in that dir.
Atlas Pty.NotFoundError and Pty.ExitedError: the terminal exited or was not found
Atlas raises Pty.NotFoundError for a missing ptyID and Pty.ExitedError when the process behind it exited. Open a new terminal and read the pty.exited event exitCode.
Atlas error: Task failed or Task cancelled from a subagent
Atlas task fails with the subagent's own error text, or with Task cancelled. Read the child's error message, open the subagent session, and re-run with a narrower prompt.
Atlas error: Failed to parse YAML frontmatter in an agent or command markdown file
Atlas exits with <path>: Failed to parse YAML frontmatter: <yaml error>. Fix the YAML between the --- fences, watching for tabs, unquoted colons, and a missing fence.
Atlas: The user rejected permission to use this specific tool call
Atlas tells the model: The user rejected permission to use this specific tool call. Approve the call, approve with always, or add an allow rule under permission in config.
Atlas error: Plugin requires atlas <range> but running <version>
Atlas throws "Plugin requires atlas <range> but running <version>" when engines.atlas does not satisfy your build. Move Atlas into the range, or update the plugin.
Atlas: OpenAI Codex token exchange failed or token refresh failed
Atlas fails OpenAI/Codex login with "Token exchange failed: <status>" or "Token refresh failed: <status>". Re-run atlas auth login; a 400 means a stale auth code.
Atlas edit error: oldString cannot be empty when editing an existing file
In Atlas an empty oldString means create a new file, so edit rejects it on a file that already exists. Supply the exact text to replace, or call write instead.
Atlas apply_patch: "Failed to find context '<context>' in <path>"
Atlas apply_patch fails with Failed to find context in <path> when the patch was built against a stale file. Re-read the file, regenerate the patch, or fall back to the edit tool.
Atlas glob tool: "glob path must be a directory: <path>"
Atlas glob fails with glob path must be a directory: <path>. Pass the directory to search in `path` and the file pattern in `pattern`, or omit path to search the instance directory.
Atlas TUI error: Creating workspace failed
Atlas shows a Creating workspace failed toast carrying the real error. Read the toast body, confirm the project is a git repository, check disk space and permissions.
Atlas: xAI device code expired, denied, or timed out
Atlas ends xAI login with "xAI device code expired", "device authorization was denied", or "timed out". Re-run atlas auth login for xai and approve promptly.
Atlas error: Failed to initialize provider. Check credentials and configuration
Atlas prints Failed to initialize provider when ProviderInitError is raised. Fix it with atlas auth login, correct provider env vars, and a valid atlas.json block.
Atlas error: Provider server overloaded or 5xx (retryable api_error)
Atlas maps server_is_overloaded and server_error to a retryable api_error and retries automatically. Wait it out, check the status page, and reduce subagent concurrency.
Atlas edit error: Found multiple matches for oldString
Atlas edit requires a unique match unless replaceAll is set. Expand oldString with more surrounding lines until it appears exactly once, or set replaceAll: true.
Atlas TUI error: Failed to copy to clipboard
Atlas shows Failed to copy to clipboard when the platform clipboard command exits non-zero. Install xclip or wl-copy, check PATH, or export the transcript to a file.
Atlas StructuredOutputError: structured output could not be parsed after retries
Atlas raises StructuredOutputError when the model's output never decodes against the schema and the retry budget runs out. Simplify the schema or change model.
Atlas read tool: "Cannot read binary file: <path>" and how to fix it
Atlas read refuses binaries with Cannot read binary file: <path>. Extract text with bash tools like strings or file, attach images as image parts, or search with grep.
Atlas error: Provider auth error, API key missing or invalid (ProviderAuthError)
Atlas raises ProviderAuthError when the AI SDK throws LoadAPIKeyError. Fix it by running atlas auth login, re-adding the credential, and deleting the stale auth entry.
Atlas error: To use Codex with your ChatGPT plan, upgrade to Plus
Atlas maps usage_not_included to a non-retryable error telling you to upgrade to Plus. Upgrade the plan, authenticate with an OpenAI API key, or pick a non-Codex model.
Atlas error: Invalid MCP URL for "<name>"
Atlas fails with Invalid MCP URL when remoteURL() cannot parse the url on a remote MCP entry. Use an absolute http:// or https:// url, or run atlas mcp add to validate it.
Atlas error: Provider has no models (ProviderNoModelsError)
Atlas raises ProviderNoModelsError when a provider loads but its model map is empty. Fix it by re-authenticating, checking plan entitlements, and removing model pins.
Atlas error: tool call denied by a permission rule
Atlas denied a tool call because the last matching permission rule was deny. Read the ruleset JSON in the message, then change that rule to ask or allow.
Atlas webfetch error: URL must start with http:// or https://
Atlas webfetch fails with URL must start with http:// or https:// when the scheme is missing. Pass a full absolute URL, and use the read tool for local files.
Atlas: Cloudflare AI Gateway token or gateway id missing
Atlas throws "CLOUDFLARE_API_TOKEN (or CF_AIG_TOKEN) is required for Cloudflare AI Gateway" or names missing exports. Set the account id, gateway id, and token.
Atlas AuthError: Failed to write auth data
Atlas raises AuthError with Failed to write auth data when the auth file cannot be written. Check permissions, ownership, and disk space, then re-run atlas auth login.
Atlas QuestionRejectedError: The user dismissed this question
Atlas raises QuestionRejectedError with the message The user dismissed this question when you dismiss a tool's prompt. Answer the question instead of dismissing it.
Atlas bash tool: "...output truncated..." and "Full output saved to: <path>"
Atlas truncates bash output at 2000 lines or 50 KB and prints Full output saved to: <path>. Read that file to see everything, or narrow the command so the useful part fits.
Atlas bash tool: "Invalid timeout value: <n>. Timeout must be a positive number."
Atlas bash fails with Invalid timeout value: <n>. Timeout must be a positive number. Pass a positive number of milliseconds, or omit timeout to use the configured default.
Atlas ACP error: provider authentication required (auth_required)
An editor on Atlas ACP gets auth_required with provider authentication required. Run atlas auth login for that provider, check ids with atlas models, restart the session.
Atlas error: Tool call not allowed while generating summary
Atlas fails with Tool call not allowed while generating summary: <toolName>. Re-run the summarization without tools, since this is a guard, not a transient failure.
Atlas GitHub Copilot error: Failed to initiate device authorization or Failed to fetch models
Atlas fails Copilot setup with Failed to initiate device authorization or Failed to fetch models. Re-run atlas auth login, choose GitHub Copilot, and check the Copilot subscription.
Atlas SessionBusyError: session is busy
Atlas throws SessionBusyError when a session is already generating. Wait for the generation to finish or cancel it, then retry the revert, unrevert, or shell.
Atlas error: default agent "<name>" not found, is a subagent, or is hidden
Atlas startup fails with default agent not found, is a subagent, or is hidden. Set default_agent to a primary agent such as build or plan, or remove the key entirely.
Atlas error: Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true
Atlas fails with Background subagents require ATLAS_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true. Export the flag and restart Atlas, or run the subagent in the foreground.
Atlas edit error: Refusing replacement because the matched span is much larger than oldString
Atlas refuses a fuzzy edit when the matched span is at least max(oldLines + 3, oldLines * 2) lines. Re-read the file and supply the full exact oldString.
Atlas error: AZURE_RESOURCE_NAME is missing
Atlas throws "AZURE_RESOURCE_NAME is missing" when the azure provider has neither a resource name nor a baseURL. Export AZURE_RESOURCE_NAME or run atlas auth login.
Atlas: MCP server has OAuth explicitly disabled
atlas mcp auth fails when a server is local or has oauth: false. Set type to remote, drop oauth: false, or use headers for a static token, then restart Atlas.
Atlas read tool: "Offset <n> is out of range for this file (<count> lines)"
Atlas read fails with Offset <n> is out of range for this file (<count> lines). Re-read without an offset to see the current length, then use an offset below that count.
Atlas edit error: File not found, or Path is a directory, not a file
Atlas edit stats the target after resolving the path. A missing stat is a not-found error and a directory is rejected. Confirm the path with glob or read first.
Atlas error: bad file reference: "{file:...}" <resolved path> does not exist
Atlas exits with bad file reference: "{file:...}" does not exist. Relative tokens resolve against the config file's directory, not your cwd. Create the file or fix the path.
Atlas error: Model not found: <provider>/<model>
Atlas exits with Model not found. Run atlas models to copy the exact provider/model id, fix the model value in atlas.json, and read the Did you mean suggestions.
Atlas error: Assistant hit the output length limit (MessageOutputLengthError)
Atlas cuts a reply short with MessageOutputLengthError when the provider stops on max output tokens. Ask for smaller pieces, use edit or apply_patch, or pick a bigger model.
Atlas error: Unauthorized, request was blocked by a gateway or proxy (401)
Atlas rewrites a 401 HTML proxy page into a readable Unauthorized message. Re-authenticate with atlas auth login, refresh your SSO session, and check the baseURL host.
Atlas MCP error: Failed to get tools after connecting
Atlas connects to an MCP server then fails with "Failed to get tools". Confirm the server implements tools/list, check pagination, raise timeout, and reconnect.
Atlas: No pending OAuth flow for MCP server
Atlas fails a login with "No pending OAuth flow for MCP server". Re-run atlas mcp auth from the same Atlas process, do not reuse an old callback URL, and check the name.
Atlas: Snowflake token exchange failed or token refresh failed
Atlas throws "Snowflake token exchange failed (<status>)" or "token refresh failed" when the OAuth token endpoint returns a non-ok response. Re-run atlas auth login.
Atlas error: codebase index failed (is the embedding server reachable?)
Atlas codebase_search returns codebase index failed (is the embedding server reachable?) when the Ollama embedder is down. Start the embedding server and re-run.
Atlas TUI error: Color reference not found in defs or theme, and Circular color reference
The Atlas TUI fails to load a theme with Color reference not found in defs or theme, or Circular color reference. Define the missing name under defs or break the cycle.
Atlas apply_patch: "Invalid patch format: missing Begin/End markers"
Atlas apply_patch rejects a patch with Invalid patch format: missing Begin/End markers. Wrap the patch in Begin and End markers, in order, unindented, with at least one hunk.
Atlas HookBlockError: a config hook blocked the tool call
Atlas throws HookBlockError when a tool.execute.before hook with blocking: true denies a tool. Read the hook message, then relax the condition or drop blocking.
Atlas error: Git is not installed
Atlas fails project init with "Git is not installed" when which("git") finds nothing on PATH. Install git, put it on the PATH of the shell that launches Atlas.
Atlas: Snowflake Cortex missing credentials (SNOWFLAKE_ACCOUNT, SNOWFLAKE_CORTEX_TOKEN)
Atlas throws "Snowflake Cortex: missing credentials" when the account or bearer token is absent. Export SNOWFLAKE_ACCOUNT and SNOWFLAKE_CORTEX_TOKEN, or use atlas auth.
Atlas asks for an external_directory permission on a path outside the project
Atlas pauses for an external_directory prompt on any path outside the project. Approve it, approve with always, or add an allow rule scoped to that directory.
Atlas: OAuth state mismatch, potential CSRF attack
Atlas rejects an MCP OAuth callback with "OAuth state mismatch". Close stale browser tabs, re-run atlas mcp auth in one pass, and set redirectUri if a proxy rewrites it.
Atlas error: Sharing is disabled in configuration
Atlas session sharing fails with Sharing is disabled in configuration. Remove "share": "disabled" from your Atlas config, run atlas login, then retry the share.
Atlas error: Forbidden, request was blocked by a gateway or proxy (403)
Atlas turns a 403 HTML proxy page into a readable Forbidden message. Verify org access to the model, ask the proxy owner to allow the Atlas egress path, and check scopes.
Atlas plan mode refuses to edit files
Atlas plan mode denies every edit by design. Run the plan_exit tool and answer Yes to switch to the build agent, or switch agents to build directly.
Atlas error: Editor exited with code <n> when opening the external editor
Atlas fails with Editor exited with code <n> or Editor exited with signal <sig>. Point EDITOR or VISUAL at a real binary and use a blocking editor like code --wait.
Atlas read tool: "File not found: <path>" and how to fix it
Atlas read fails with File not found: <path>. Fix it by picking from the Did you mean one of these? list, locating the file with glob, or checking the instance directory.
Atlas error: Directory "<dir>" is not valid. Rename the directory or remove it.
Atlas exits with Directory "<dir>" in <path> is not valid. This is a common typo. Rename the folder to the exact suggestion Atlas prints, or delete it, then re-run Atlas.
Atlas error "Connection reset by server" (ECONNRESET): how to fix it
Atlas shows "Connection reset by server" with metadata code ECONNRESET when the TLS connection is dropped. Retry, then check your proxy, VPN, or firewall.
Atlas error: Provider response headers timed out after <ms>ms
Atlas raises ProviderHeaderTimeoutError when a provider stream is slow to send headers. Retry, check for a buffering proxy, and measure first-byte time on the baseURL.
Atlas error: Not logged in. Run: atlas login (and Session expired)
Atlas account operations fail with Not logged in. Run: atlas login, or Session expired. Run: atlas login. Fix it by running atlas login and completing the browser flow.
Atlas webfetch error: Request timed out
Atlas webfetch dies with Request timed out when the deadline passes. Raise the timeout parameter, check proxy and firewall reachability, then retry the fetch.
Atlas error: Input exceeds context window of this model (ContextOverflowError)
Atlas raises ContextOverflowError when the prompt is too big for the model. Fix it by compacting the session, dropping pasted files, or switching model via atlas models.
Atlas error: Session not found or Message not found
Atlas fails with Session not found: <id> or Invalid session ID: <reason>. Run atlas session to list real ids, check the branded prefix, and copy one verbatim.
Atlas error: CLOUDFLARE_ACCOUNT_ID is missing
Atlas throws "CLOUDFLARE_ACCOUNT_ID is missing" on Cloudflare Workers AI models. Run export CLOUDFLARE_ACCOUNT_ID=<your-account-id> or atlas auth login for cloudflare.
Atlas ContentFilterError: response blocked by the provider content filter
Atlas raises ContentFilterError when the provider's moderation filter blocks the response. Rephrase the prompt, remove pasted content, or switch model. Do not retry.
atlas mcp add rejects the arguments: url, command, env, header
atlas mcp add fails when the flags do not match the transport. Pass a server name, use --url for remote or a command after --, and keep --env local, --header remote.