# Troubleshooting

Source: https://athas.dev/docs/troubleshooting

Resolve startup, language tooling, terminal, AI, and connection problems with actionable checks.

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](https://athas.dev/download). 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](https://athas.dev/docs/installation) and [Updates](https://athas.dev/docs/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](https://athas.dev/docs/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](https://athas.dev/docs/terminal) and [WSL](https://athas.dev/docs/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](https://athas.dev/docs/ai-providers), [External agents](https://athas.dev/docs/external-agents) and [MCP](https://athas.dev/docs/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](https://github.com/athasdev/athas/issues).

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](https://athas.dev/docs/telemetry) explains what the app sends automatically.