# Troubleshooting

What to do when the engine won't start, a sign-in doesn't finish, or something else goes wrong.

## The engine won't start

**Settings › Engine** shows whether the engine is running. **Restart**, next to it, starts it again; your sessions and accounts are kept.

- **On first launch**, the engine downloads from the npm registry. If that fails, check your connection, VPN or firewall, then click **Try Again**. If it says the download didn't match or isn't signed, something on your network changed the file: try another network.
- **If it takes too long**, macOS may be waiting for you to allow access to a folder. Look for that dialog, which can be behind other windows, and click **Allow**.

## A machine won't connect

**Settings › Machines** shows each machine's status; point at it to see why it failed, and click **Connect** to try again.

- **The host key isn't known**: connect to the machine once in Terminal with `ssh`, and accept its key.
- **The key isn't accepted**: Kuvo Code uses your SSH keys and agent, never a password. Check that `ssh <host> true` works in Terminal without asking for anything.
- **The machine isn't supported**: the engine runs on Linux on x86-64 or ARM64, but not on Alpine.

## A sign-in doesn't finish

Click **Open the Page Again** if the browser page closed, or **Cancel** and connect again. If the provider offers an API key, that's a reliable alternative. See [Accounts](/code/docs/accounts/).

## A model is missing

The model picker lists models from providers you've connected, plus the free ones. Connect the provider in **Accounts** (<kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>K</kbd>).

## Can't read or change files in a folder

macOS asks before an app uses your Desktop, Documents or Downloads folders. If you clicked **Don't Allow**, turn access back on in **System Settings › Privacy & Security › Files & Folders**, under **Kuvo Code**.

## Logs

The engine's logs are in `~/Library/Application Support/run.kuvo.code/opencode/data/opencode/log`; **Settings › Engine › Show in Finder** opens the folder above it.

## Report a problem

Choose **Help › Report an Issue…**, in the menu bar or the menu at the bottom of the sidebar, or [open an issue on GitHub](https://github.com/serhatandic/kuvo-code/issues/new/choose), with your Kuvo Code and macOS versions, what happened, and the end of the newest engine log if the engine is involved. Logs can include your prompts, code and file paths, so remove anything private first.

Problems with the agent itself that also happen in opencode belong with [opencode](https://github.com/anomalyco/opencode/issues). Report security problems [privately](https://github.com/serhatandic/kuvo-code/security/advisories/new).