Support

Troubleshooting and FAQ

In this handbookContents

This page covers common states surfaced by the current app code.

Local engine unreachable

If Local (Ollama) cannot be reached, use Set Up AI… or the Local AI Engine panel in Settings ▸ AI. The UI can offer retry, reinstall, update Ollama, or a cloud-key path depending on the failure.

If AITerm reports an integrity failure, use the reinstall path. If it reports that you appear offline, reconnect and retry, or use a cloud key.

Provider auth errors

For OpenAI, Anthropic, OpenAI-compatible providers, Azure OpenAI, and Bedrock, check the provider-specific fields in Settings ▸ AI. Missing keys or missing base URLs fail closed rather than silently falling back to another provider.

Named custom servers use per-server key slots. If a saved server's address differs from the one in use, Settings ▸ AI shows a notice under its key field with a Use saved address button: click it, enter the key, then click Apply (Add Connection for an Azure server).

For Claude Code or Codex CLI delegation, make sure the official CLI is installed and signed in. AITerm detects that the CLI is installed; Check in Settings ▸ AI confirms sign-in before the first request (switching to the CLI runs a check too). The sign-in action runs the CLI's own login command in a terminal tab; setup’s door offers Sign in… when the check says the CLI isn’t signed in. If the failure says "Update Claude Code to 2.1.169 or later" or "Update Codex to 0.153.3 or later", the installed CLI is older than the version AITerm needs to switch its tools off; run claude update or codex update and retry.

For Amazon Bedrock with an AWS profile, an expired SSO session is the most common failure. Run aws sso login --profile <name> in a terminal, then retry. If Save is disabled in the Bedrock sheet, it names the exact missing field (region, credentials, or model id).

For Azure OpenAI, the resource name, deployment name, and key all come from the Azure Portal (Keys and Endpoint, and the Deployments tab). A wrong deployment name is a common cause of failures — in Azure it is the name you gave the deployment, not the base model name.

For managed MLX or Ollama, if the model list can't load you can still type a model id directly: an mlx-community repo id for MLX, or a model name like llama3 for Ollama. See AI Providers and Models for the full per-provider setup.

"AI off" on the model chip

When the selected AI connection can't start — a missing key, a CLI that isn't installed, a local engine that isn't running — AITerm turns AI off instead of sending anything somewhere else. The model chip in the status bar shows a warning sign and AI off; hover over it to read why. Every AI request gives the same reason, and nothing is sent anywhere until you fix the connection in Settings ▸ AI or pick another one from the chip.

The chip names the connection (a saved server's name, a preset's, Claude Code or Codex), followed by its model when the connection uses one, or choose a model when none is chosen. It carries the connection check's mark: a green check when the connection last answered, and an orange mark when a check or a request failed for a reason you need to fix (a rejected key, a signed-out CLI, a stopped engine) or when the check is waiting for your OK. A request that fails for a passing reason (a timeout, a server error, the network) only takes the green check away until the next answer. Hover for the reason, and use Check connection in its menu (Allow cloud use… while the check waits for your OK).

What the connection check says

Check in Settings ▸ AI, or Check connection in the menu of the connection chip in the status bar, sends one short message — “Reply with the single word OK.” — to the applied connection, and nothing from the terminal. A check also runs by itself after you switch connections, after Apply (not when the Apply left the connection unchanged and it is already working), and at launch. A launch check is skipped when the connection answered in the last 24 hours, and the line then shows when it last worked. The result is one line; here is each one and what to do:

Working — … answered … — nothing to do.
AI is off — … Nothing is sent anywhere. — the connection answered, but AITerm can't use it right now; the reason says why (see "AI off" on the model chip, above).
Checking … — the check is running; Cancel stops it.
Not checked yet. / Worked on …; not checked since. — click Check. The second also follows a request that failed for a passing reason.
Not checked — the check waits for your OK to use a cloud model. — click Allow cloud use… in the chip's menu or Review… in Settings ▸ AI and allow cloud use (the check then runs), or pick a local connection. Nothing was sent.
… rejected the API key (Bedrock: … rejected the credentials) — check the key in Settings ▸ AI, then Check.
AITerm couldn’t read the … key from your Keychain. — unlock the Keychain, then pick the connection again.
… isn’t set up: … — the reason names the missing piece (a key, an address, a model, a moved server); fix it in Settings ▸ AI, and Apply checks again.
Couldn’t reach … — you may be offline, or the address in Settings ▸ AI may be wrong.
… didn’t answer within N s. — try again; a large local model can take a while to load the first time. A check waits 30 s for a cloud connection or a CLI, and 90 s for one on this Mac.
… isn’t installed where AITerm can find it. — install the CLI, then Check.
… isn’t signed in. — Sign in / switch account, then Check.
Update Claude Code to … or later / Update Codex to … or later — run the update, then Check.
… doesn’t offer the model … / Ollama doesn’t have … — choose another model in Settings ▸ AI, or for Ollama pull it in Model Manager.
Local AI isn't running yet. — Set Up AI…, or start the engine.
Local AI isn't running yet. Choose MLX (managed) in Settings ▸ AI to start it. — managed MLX is set up in Settings ▸ AI, not in the setup sheet. The status bar's reminder and the input bar's notice take you there, and the check row in Settings ▸ AI points at the MLX (managed) tile.
… answered with an error (HTTP …) / … is rate-limiting you — wait a moment, then Check again.
… didn’t answer: … — the provider's or the CLI's own words; Check again, or review the connection in Settings ▸ AI.

Why was my command confirmed?

The active gate result can come from the command's risk tier, your global Safety Profile, a per-host SSH floor, or an imported policy pack. The confirmation text names the binding reason when it can.

Use Settings ▸ Security to review the current profile, security toggles, host profiles, and policy pack.

Why was my command blocked?

Production blocks Irreversible commands. Locked Down blocks Destructive and Irreversible commands. Policy packs can also deny matching commands. A block means AITerm did not send that command to the shell.

If you need to perform the task, use a safer command, temporarily remove the relevant policy layer, or switch to a less strict profile only when that is appropriate for the machine you are on.

License activation issues

Use Upgrade to Pro… or Subscribe / Manage Plan… from the app menu, then Activation to enter or refresh your license. AITerm verifies server-signed license tokens locally and can remain Pro during valid offline grace. Expired or definitively rejected licenses drop to Free.

I typed plain English and it ran literally

Use a leading ? or : to force the AI path. A leading space forces literal shell mode.

Some lines are genuinely ambiguous — find largest file here starts with a real command — so AITerm runs them exactly as typed rather than guessing. When such a line comes back with an error, or with nothing (a grep that matched no lines), the suggestion above the input bar carries an extra Interpret as English link: beside Fix and Explain when there is an error worth diagnosing, and on its own when there isn't. Click it and AITerm asks the AI what you meant; the answer arrives as an editable proposal that still runs only when you press Enter.

Stopping a command yourself with Ctrl-C is not a failure, so nothing is suggested afterwards.

Where do I get help?

Use the public AITerm feedback tracker or email support@ai-term.com. Include your AITerm version, provider type, the visible error message, and whether the issue is local-only or cloud-provider-specific.

In AITerm, choose Help ▸ Report a Problem…: it opens the tracker's bug form in your browser with your AITerm version, macOS version, your Mac's chip (for example Apple M4), AI provider type and safety profile filled in — never a key, server address, model, command or anything from your terminal. Describe what happened, what you expected, and the steps. The crash report sheet's Copy & report on GitHub opens the same form, with the report on your clipboard to paste in.