# Troubleshooting

Fixes for the common problems: an install that stops, an agent that will not start, provider errors and retries, and a device that shows offline.

*Where in Studio: Studio → Settings*

*Last updated: 2026-10-25*

Find the message you see below and follow the fix. If nothing here helps, [report the problem](https://kelrova.com/docs/studio/reference/support) from Studio with diagnostics attached.

## Installing

### The install command on a Mac

The one-line installer is for Linux only. On a Mac it stops with `on macOS, download the desktop app instead`. Download the macOS app (Apple Silicon) instead; see [Install on macOS](https://kelrova.com/docs/studio/getting-started/install-macos).

### Linux install messages

The installer prints what went wrong and the command that fixes it. The common ones:

| Message | Fix |
| --- | --- |
| `unsupported architecture` | Studio runs on Linux x86_64 and ARM64 only. |
| `could not install runtime libraries` | Run the `sudo apt-get install` command it prints, then run the installer again. |
| `kelrova` not found after the install | Open a new SSH session, or run `export PATH="$HOME/.local/bin:$PATH"`. |
| `systemd user session not available` | You are probably root through `sudo su`. Log in as a regular user and run the installer again, or start the engine by hand with `kelrova headless`. |
| `could not enable linger` | Without it the engine stops when you log out. Run the `sudo loginctl enable-linger` command it prints. |
| `the kelrova service failed to restart` | Check `systemctl --user status kelrova` and `journalctl --user -u kelrova`. |
| `--login needs an interactive terminal` | Connect with `ssh -t`, then run the sign-in command again. |
| `sign-in did not finish, so the engine runs local-only` | Run the sign-in command it prints again. |
| `could not install the codex CLI`, `Claude Code` or `Devin` | The installer prints the vendor's own install command. Run it, then check the device's packages in Studio. |
| `chrome not found — browser tools unavailable` | Run the installer again with `--with-chrome`. Google's Chrome repository is x86_64 only; on ARM64 install `chromium` yourself and run the installer again. |
| `git not found` | Install git (`sudo apt-get install -y git`) to work with repositories. |

The sign-in command is the installer with `--login`:

```bash
curl -fsSL https://studio.kelrova.com/install.sh | sh -s -- --login
```

See [Install on Linux](https://kelrova.com/docs/studio/getting-started/install-linux) and [Add a server](https://kelrova.com/docs/studio/devices/add-server).

## Agents

### An agent is missing from the composer

Open **Settings → Agents** and pick the device in the menu at the top right, because each device has its own agents. Then read the agent's row:

- **Not installed**: install the agent's command-line tool on that device. The pane says which one.
- **Off**: turn on **Show in composer**. At least one agent must stay on.
- **No account** or **No active account**: choose **Add account**, or **Switch** to an account you added.

See [Connect your agents](https://kelrova.com/docs/studio/getting-started/agents).

### Sign in again

The provider rejected the account's login, so the agent cannot run. Choose **Renew login** on the account in **Settings → Agents**.

### Model unavailable

The provider could not verify or use the selected model. Open **Settings → Devices & security**, select the device that runs the chat and choose **Check packages** under **Maintenance**. It lists every agent tool the device should have, with installed or missing status. Fix what is missing, then retry the message.

## Provider errors and retries

When a provider cuts a turn short, an error row appears in the chat. It names the reason and the agent, for example **Session limit reached · Claude Code**, and **Details** unfolds the provider's own message.

| Row | What Studio does |
| --- | --- |
| **Provider at capacity**, **Rate limited**, **Connection lost** | Retries automatically after a delay that doubles each time. |
| **Session limit reached**, **Weekly limit reached**, **Usage limit reached** | Waits for the limit to reset, then retries, if the reset falls within the longest wait. |
| **Authentication unavailable**, **Model unavailable**, **Adapter crashed**, **Startup failed**, **Invalid request**, **Refusal**, **Provider error** | **Not retried automatically.** Fix the cause and choose **Retry**. |

While a retry waits, the row says **Retrying in …** with **Attempt N of M**, or **Resets …** for a limit, and the chat's row in the sidebar says **Retry in …**. Choose **Retry now** to go at once or **Cancel** to stop waiting. When nothing is scheduled the row says why: **Automatic retry is off**, **Automatic retries used up** or **Too far off to retry automatically**, the last for a limit that resets later than the longest wait, typically a weekly one. In an Orchestra run, a subagent waiting on its provider keeps its place and the run waits for it.

![A provider error row in a chat reading Session limit reached, with the reset time, Retry now and Cancel.](https://kelrova.com/docs/img/studio-reference/provider-retry.png)

*A provider error row waiting to retry, with Retry now and Cancel.*

### Change how Studio retries

Open **Settings → Agents → Provider retry**. The setting is synced across your devices.

| Setting | Default | Range |
| --- | --- | --- |
| **Retry automatically** | On | |
| **Chats** and **Subagents** | On | |
| **Attempts** | 4 | 1 to 10 |
| **First delay** (doubles after each retry) | 30 seconds | 5 to 600 seconds |
| **Longest delay** | 600 seconds | 30 to 3,600 seconds |
| **Wait for the limit to reset** | On | |
| **Longest wait** | 300 minutes | 15 to 1,380 minutes |

With **Retry automatically** off, failed turns and subagents stop until you retry them.

## Devices

### A device shows Waiting or Offline

Each device reports in about once a minute.

- **Online**: it reported recently.
- **Waiting**: a report is late, but the device is probably between reports. Nothing is wrong yet.
- **Offline**: no report for a few minutes. The device is asleep, powered off or cut off from the network.

You can still send to an offline device. The composer says so first, for example **build-server is offline. A message sent now starts once it reconnects.**, and the work starts when the device is back. On a server, check the engine with `systemctl --user status kelrova`. See [Device status](https://kelrova.com/docs/studio/devices/status).

### Pair to run chats on a device

From another computer, only approved devices can run chats, commands and terminals. If a device's pane in **Settings → Devices & security** says **Pair to run chats, commands and terminals on** that device, choose **Request access**: a six-digit code appears, and you type it on the other device. If it says the device **answered with a different key than the one you paired**, pair again before working on it. If it **didn't answer the access check**, make sure it is online and try again. See [Approved devices and signatures](https://kelrova.com/docs/studio/trust/approved-devices).

### A server that stays offline

Once a server has been offline for a few minutes, its pane offers to reconnect it without losing its projects and chats. To take it out of your account, see [Remove a device](https://kelrova.com/docs/studio/devices/remove).

## Sync and updates

- **Settings → Sync status** shows each queue item as **Up to date**, **Syncing**, **Queued** or **Needs attention**. Signed out, sync is off and your work stays on this device. See [What stays on your computer and what syncs](https://kelrova.com/docs/studio/trust/data).
- **Settings → About** shows the update state. **Update failed — view details to retry.** opens the reason with **Details**. See [Signed updates](https://kelrova.com/docs/studio/trust/updates).

## Context usage is empty

**Context usage will appear after the active agent reports its context window.** The numbers appear after the agent's first turn. See [Token usage](https://kelrova.com/docs/studio/reference/usage).

## Related

- [Report a problem](https://kelrova.com/docs/studio/reference/support)
- [Device status](https://kelrova.com/docs/studio/devices/status)
- [Install on Linux](https://kelrova.com/docs/studio/getting-started/install-linux)
- [Connect your agents](https://kelrova.com/docs/studio/getting-started/agents)