Troubleshooting

Start with Doctor

Open Settings → Coding agents and choose Scan coding tools. Check the report time so you know you are looking at a fresh scan. Doctor shows the selected install, version support, login state, runtime, and workspace checks.

If diagnostics cannot refresh, the app keeps the previous report. Reconnect before treating those older results as current.

The tool is not found

1. Confirm the CLI runs in a terminal. An installed desktop editor may still need a separate CLI installation.
2. Check that you installed the executable listed in Agent setup.
3. Run Scan coding tools again. If available, expand All detected installs to see alternative or broken installations.
4. If Doctor says Integration not verified, use one of the documented integrations for your first chat.

Sign-in is required or unknown

Run the tool’s native sign-in command, finish authentication, then scan again. If several copies of a CLI exist, make sure you are signing in with the executable Doctor reports.

API key configured and Signed in are different states. Login unknown means the scan could not establish login status; it is not confirmation that a session will work.

The chat will not connect

If a read-only profile cannot connect because the provider offers no safe mode, choose a provider that supports the required permission mode. Only choose broader permissions when you intend to allow them.

1. Check that the local daemon is connected. If the app is reconnecting, wait for it to come online before retrying diagnostics.
2. In a source build, keep both pnpm dev:ui and pnpm dev:desktop running.
3. Check the chat’s Context panel and connection banner for sign-in or provider-specific guidance.
4. Confirm that the same CLI can run directly, then retry in Zoltbot. Update an unsupported CLI before retrying.

A version is newer than tested

Newer than tested means your CLI is ahead of the tested version in its definition. It does not mean the new version has been verified. Older than tested, Unsupported version, and Version support unknown also need review if a connection fails.

After changing an installation, scan again. Do not assume that a successful scan proves every runtime capability works.

Still stuck?

Open an issue with the Zoltbot version, macOS version, provider and CLI version, the exact error, and the steps that reproduce it. Review anything you attach and remove credentials, private conversation content, and personal file paths.

For security reports, use the repository’s security policy.