Troubleshooting
Resolve startup, language tooling, terminal, AI, and connection problems with actionable checks.
Updated
Start with the symptom, the affected workspace, and the exact error. Change one thing at a time so you can tell what fixed the problem.
App will not start
Check that the downloaded artifact matches your OS and CPU architecture. Try a current stable installer from the download page. On Linux, the portable bundle uses system WebKitGTK 4.1; a missing shared-library error identifies a runtime dependency to install through your distribution.
Do not remove settings or bypass OS security checks as your first step. Report the exact launch error and install method. See Installation and Updates.
No symbols, completions or diagnostics
Confirm the active project root, detected language and enabled integration. Install project requirements, inspect LSP: Show Status, then run Language Server: Restart All Servers. See Language servers.
Terminal will not launch
Check the selected shell/profile in Settings and try running that shell outside Athas. Confirm its startup directory still exists. On Windows, confirm the selected WSL distribution is installed. If shell integration changes prompt behavior, turn it off temporarily to compare. See Terminal and WSL.
AI request fails
Check the selected model and connection, network access, key validity and provider error. A hosted credit/cap error differs from a provider-key error. External agents authenticate through their own CLI. Custom endpoints need the exact model ID and a supported API. See Providers and Models, External agents and MCP.
Command or panel is missing
Search the command palette and confirm the feature is enabled in Settings. Some commands require an open file, a Git repository, an installed integration, or a particular plan. Inspect the current keymap rather than assuming a shortcut from another editor.
Collect a useful report
Run Developer: Open Athas Log from the command palette and inspect the relevant error. Use the bug-report action in General settings or open an issue.
Include:
- Athas version, OS version, CPU architecture and installation method.
- What you expected, what happened, and repeatable steps.
- The affected language, integration, shell or provider, when relevant.
- A small sample project or screenshot and relevant log lines.
Remove tokens, passwords, personal paths and private project contents before sharing a report. Telemetry explains what the app sends automatically.