Troubleshooting and FAQ

Support · mixed

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 ▸ LLM. 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 ▸ LLM. Missing keys or missing base URLs fail closed rather than silently falling back to another provider.

Named custom servers use per-server key slots. Re-enter the key for the selected server if a saved server cannot authenticate.

For Claude Code or Codex CLI delegation, make sure the official CLI is installed and signed in. The sign-in action runs the CLI's own login command in a terminal tab.

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.

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 Dangerous commands. Locked Down blocks Destructive and Dangerous 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 short inputs are ambiguous, so AITerm may run them literally and then offer translation if the shell says command not found.

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.