# Troubleshooting

> Common failure modes: runtime not reachable, selector ambiguity on remote CLI, worktree delete preflight, terminal/orchestration timeouts, and platform-specific native dependency issues.

- Repository: stablyai/orca
- GitHub: https://github.com/stablyai/orca
- Human docs: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c
- Complete Markdown: https://grok-wiki.com/public/docs/stablyai-orca-2036d532bf1c/llms-full.txt

## Source Files

- `src/cli/format.ts`
- `src/cli/runtime-client.ts`
- `docs/worktree-delete-preflight.md`
- `src/main/runtime/worktree-teardown.ts`
- `config/scripts/ensure-native-runtime.mjs`
- `src/cli/help.ts`

---

---
title: "Troubleshooting"
description: "Common failure modes: runtime not reachable, selector ambiguity on remote CLI, worktree delete preflight, terminal/orchestration timeouts, and platform-specific native dependency issues."
---

The Orca CLI talks to a running runtime over a local Unix socket or named pipe, or over an encrypted WebSocket when you pass `--pairing-code` / `--environment`. Most commands fail fast with stable error codes (`runtime_unavailable`, `selector_ambiguous`, `timeout`) that `formatCliError` and RPC `mapRuntimeError` turn into human text or JSON envelopes.

## Runtime not reachable

### Local desktop runtime

| Symptom | Typical cause | What to try |
| --- | --- | --- |
| `runtime_unavailable` + “Orca is not running. Run `orca open` first.” | No live runtime socket, or metadata missing | Run `orca open`, then `orca status` |
| `runtimeReachable: false` with `runtimeState: not_running` | App never started in this user-data dir | Start Orca; confirm `appRunning` becomes true |
| `runtimeState: stale_bootstrap` | Metadata file exists but socket does not answer | Quit stale Orca processes; restart the app |
| `runtimeState: starting` / `graph_not_ready` | App up, graph not hydrated yet | Wait and retry; check `graphState` in `orca status --json` |
| “Could not connect to the running Orca app” | Socket error while connecting | Restart Orca; on Windows verify named-pipe transport in metadata |
| “No compatible transport found” | Metadata lacks `unix` or `named-pipe` endpoint | Restart Orca so bootstrap rewrites `orca-runtime.json` |
| `runtime_timeout` | No RPC frame within client timeout (default 60s) | Retry; for long polls see terminal/orchestration sections |
| `runtime_open_timeout` | `orca open` waited 15s without reachability | Launch Orca manually; set `ORCA_APP_EXECUTABLE` or `ORCA_OPEN_COMMAND` for nonstandard installs |

<Steps>
<Step title="Verify local readiness">

```bash
orca status
orca status --json
```

Expect `runtimeReachable: true` and `runtimeState: ready` (or `graphState: ready` in JSON) before repo, worktree, or terminal commands.

</Step>
<Step title="Target the correct instance">

Dev and parallel installs use a separate user-data directory. Point the CLI at the same metadata Electron writes:

```bash
export ORCA_USER_DATA_PATH="$HOME/Library/Application Support/orca-dev"   # example
orca status
```

Packaged defaults: macOS `~/Library/Application Support/orca`, Windows `%APPDATA%\orca`, Linux `$XDG_CONFIG_HOME/orca` (or `~/.config/orca`).

</Step>
</Steps>

### Headless `orca serve`

`orca serve` exposes the same RPC surface without the renderer. If the CLI still cannot connect, confirm serve wrote bootstrap metadata under the same `ORCA_USER_DATA_PATH` you use for other commands.

### Remote runtime (`--pairing-code`, `--environment`)

| Code | Meaning |
| --- | --- |
| `remote_runtime_unavailable` | WebSocket failed or closed mid-request |
| `runtime_timeout` | Remote RPC exceeded the client timeout |
| `incompatible_runtime` | Protocol version mismatch between CLI and server |
| `invalid_argument` | Bad pairing payload, endpoint, or both `--pairing-code` and `--environment` |

Remote pairing uses `sendRemoteRuntimeRequest` with the same keepalive-aware timeout extension as local long polls. After connect, the CLI checks `status.get` and blocks further RPCs when `evaluateRuntimeCompat` reports `client-too-old` or `server-too-old`.

<Warning>
Do not pass `--pairing-code` and `--environment` together. Use one targeting mechanism per invocation.
</Warning>

Environment names resolve from disk; duplicate names throw before any network call:

```
Environment name "<name>" is ambiguous; use the environment id.
```

## Selector ambiguity on remote CLI

Worktree and repo selectors are resolved server-side in `resolveWorktreeSelector` / `resolveRepoSelector`. When more than one record matches, the runtime throws `selector_ambiguous` (passthrough RPC code).

### Worktree selector grammar

| Form | Matches |
| --- | --- |
| `id:<uuid>` | Exact worktree id |
| `path:<absolute-path>` | Filesystem path (normalized compare) |
| `branch:<name>` | Branch ref (`refs/heads/…` normalized) |
| `issue:<number>` | Linked issue metadata |
| bare string | id, path, or branch (same rules as unprefixed) |
| `active` / `current` | **Local CLI only** — see below |

### Repo selector grammar

| Form | Matches |
| --- | --- |
| `id:<id>` | Repo id |
| `path:<path>` | Registered repo root |
| `name:<displayName>` | Display name |
| bare string | id, path, or display name |

### Remote CLI constraints

Paired CLIs cannot use cwd-derived shortcuts. `assertLocalCwdWorktreeSelector` rejects `active`, `current`, and the implicit cwd default used for browser/computer commands:

```
active is a local cwd shortcut and cannot be resolved against a remote runtime.
Pass an explicit server-side worktree selector such as id:<id>, branch:<branch>,
issue:<number>, or path:<absolute-server-path>.
```

<Steps>
<Step title="List candidates on the server">

```bash
orca worktree list --json --environment <id>
orca repo list --json --environment <id>
```

</Step>
<Step title="Disambiguate">

Prefer `id:` selectors in scripts. For branches shared across worktrees, narrow with `path:` on the server filesystem or tie-break with `issue:`.

Locally, `orca worktree current` resolves cwd to `id:<id>` so duplicate paths across repo registrations do not surface as `selector_ambiguous`.

</Step>
</Steps>

### JSON shape

With `--json`, failures return the RPC envelope:

```json
{
  "ok": false,
  "error": { "code": "selector_ambiguous", "message": "selector_ambiguous" }
}
```

Some lineage errors include `data.nextSteps`; the CLI prints those as “Next step: …” lines after the message.

## Worktree delete preflight

Non-force local deletes run `assertWorktreeCleanForRemoval` **before** PTY teardown. The helper runs `git status --porcelain --untracked-files=all` in the worktree directory; any output throws “Worktree has uncommitted or untracked changes.” Force deletes skip preflight and keep the historical order: kill PTYs, then `git worktree remove`.

```text
non-force local delete:  preflight → killAllProcessesForWorktree → removeWorktree
force delete:            kill → removeWorktree (no preflight)
SSH-backed repo:         provider API only (no local PTY sweep)
```

### Failure classes

| Situation | PTYs killed? | User-visible error |
| --- | --- | --- |
| Dirty / untracked (non-force) | No | `formatWorktreeRemovalError` + porcelain stdout |
| Preflight git subprocess error | No | Same formatter with stderr/stdout |
| Orphan / missing worktree (`not a working tree`, `not a git repository`, `ENOENT`) | No | Falls through to existing orphan cleanup path |
| Successful preflight | Yes | Normal removal |

<Tip>
Commit, stash, or discard changes before `orca worktree rm`. Use `--force` only when you accept destroying dirty state and killing terminals first.
</Tip>

PTY teardown is best-effort across renderer graph, provider session list (`${worktreeId}@@` prefix), and `pty-registry`; git removal still proceeds even if some kills fail.

## Terminal and orchestration timeouts

### Client timeout policy

| Layer | Default | Long-poll behavior |
| --- | --- | --- |
| `RuntimeClient` socket | 60_000 ms | — |
| `terminal.wait` | Inner budget from `--timeout-ms`; RPC cap `timeoutMs + 5000` or **5 min** if unset | Client uses `inner + 10s` grace (`LONG_POLL_CLIENT_GRACE_MS`) |
| `orchestration.check --wait` | Server waiter uses `--timeout-ms` | Same client grace when `wait: true` |
| `orchestration.ask` | Default **600_000** ms server-side | Poll loop respects remaining budget |
| Transport keepalives | — | `_keepalive` frames refresh the client timer during long polls |

Local Unix transport and remote WebSocket both ignore keepalive lines and only settle on a terminal success/failure frame matching the request id.

### `orca terminal wait`

Supported conditions: `exit`, `tui-idle`.

| Outcome | `satisfied` | Exit code | Notes |
| --- | --- | --- | --- |
| Condition met | `true` | 0 | — |
| Blocked interactive prompt | `false` | 1 | `blockedReason` set (Codex trust/update/CWD/hooks, etc.) |
| Server `timeout` error | RPC failure | non-zero | Thrown when waiter budget expires |
| Client `runtime_timeout` | — | non-zero | Socket gave up before server responded |

`tui-idle` uses a **5 minute** default server timeout when `--timeout-ms` is omitted, so unrecognized agents do not hang forever. `exit` waits without a default cap unless you pass `--timeout-ms`.

Example:

```bash
orca terminal wait --terminal term_abc --for tui-idle --timeout-ms 120000 --json
```

Inspect `blockedReason` in JSON when `satisfied: false` — automation should send input or focus the pane instead of retrying the same wait.

### `orca orchestration check --wait`

Blocking check replaces sleep/poll loops. Pass `--wait` and optionally `--timeout-ms`. The server long-poll releases promptly when the client disconnects (`signal` abort), rather than holding the slot for the full timeout.

Ensure the experimental orchestration feature and runtime are running; otherwise RPCs return `runtime_unavailable`.

### Terminal read limits

`terminal read` may return `warning: output limited` with `oldestCursor` / `nextCursor`. Page retained output with `--cursor` and `--limit` instead of treating truncation as a hang.

## Platform-specific native dependency issues

Orca depends on native addons **`better-sqlite3`** and **`node-pty`**. Electron builds also rebuild **`cpu-features`** via `config/scripts/rebuild-native-deps.mjs`.

### Detection and auto-rebuild

`config/scripts/ensure-native-runtime.mjs` verifies loads in a **child process** (a failed `.node` load must not poison the parent):

| Flag | Runtime checked |
| --- | --- |
| `--runtime=node` | Node used by Vitest / CLI typecheck pipelines |
| `--runtime=electron` | Electron binary with `ELECTRON_RUN_AS_NODE=1` |

On failure it runs `pnpm rebuild <modules>` (Node) or `rebuild-native-deps.mjs` (Electron), then re-checks.

`pnpm dev`, `pnpm test`, and `ensure:electron-runtime` invoke this script automatically.

### Common load failures

| Message pattern | Likely cause | Fix |
| --- | --- | --- |
| `MODULE_VERSION` / ABI mismatch | Node/Electron upgraded without rebuild | `pnpm rebuild:node` or `pnpm rebuild:electron` |
| `better-sqlite3` fails on `new Database(':memory:')` | Binding not built for current ABI | Same rebuild; confirm install completed |
| `node-pty` / `pty.node` / `conpty.node` | Windows build < 18309 uses `pty`; newer uses `conpty` | Re-run ensure script on target OS |
| Script exits 1 after rebuild | Toolchain or headers missing | Install build tools; delete `node_modules` and `pnpm install` |

Manual checks:

```bash
node config/scripts/ensure-native-runtime.mjs --runtime=node
node config/scripts/ensure-native-runtime.mjs --runtime=electron
```

### macOS computer-use (optional)

Computer automation adds separate native artifacts (`build:computer-macos`, `verify:computer-native`). Failures there do not block core terminal/runtime features but break `orca computer *` until natives are built.

## Quick diagnostic map

```mermaid
flowchart TD
  CLI[orca CLI command]
  CLI --> Local{Remote flags?}
  Local -->|no| Meta[Read orca-runtime.json]
  Meta --> Sock[Unix / named-pipe RPC]
  Local -->|yes| WS[E2EE WebSocket]
  Sock --> Ready{runtime reachable?}
  WS --> Ready
  Ready -->|no| Open[orca open / fix pairing]
  Ready -->|yes| Sel[Resolve selectors]
  Sel -->|ambiguous| List[worktree/repo list --json]
  Sel -->|ok| Op[terminal / worktree / orchestration RPC]
  Op -->|timeout| Tune[Increase timeout-ms + grace]
  Op -->|dirty delete| Clean[git status / --force]
```

## Related pages

<CardGroup>
<Card title="Runtime environments" href="/runtime-environments">
Pairing codes, saved environments, `orca serve`, and remote targeting flags.
</Card>
<Card title="Selectors and JSON output" href="/selectors-json-output">
Selector grammar, `--json` errors, and remote resolution rules.
</Card>
<Card title="CLI core reference" href="/cli-core-reference">
`open`, `status`, `worktree rm`, `terminal wait`, and environment commands.
</Card>
<Card title="Agent orchestration" href="/agent-orchestration">
Blocking `orchestration check`, timeouts, and coordinator prerequisites.
</Card>
<Card title="Develop and build" href="/develop-and-build">
Native rebuild scripts, Electron dev startup, and platform artifacts.
</Card>
</CardGroup>