Troubleshooting

CLI and CI

Node.js version too old / install fails. The CLI needs Node.js 18+ (Node 20 recommended). On Ubuntu CI, the distro default can be too old — use actions/setup-node@v4 or NodeSource. Always use npx -y in CI: bare npx prompts "Ok to proceed?" on first install and hangs a non-interactive shell.

LLM access denied / quota errors (cloud). The account behind the service key isn't entitled to the managed LLM, or has hit its limit. Upgrade to a plan that includes managed LLM. A quota block exits 2 (permanent — do not retry), not 3.

Exit 2 vs 3. 2 is a usage/configuration error (bad flags, not authenticated, a selector that matched nothing) — nothing ran, and retrying won't help. 3 is a transient infra/runtime error (engine unreachable, auth exchange failure) — safe to retry. See CI Integration.

A run "passed" but executed zero plans. A run that executes zero plans is a configuration error, not a pass — check that the service key's project has plans and that your --plan-id / --label-ids selectors match. The GitHub Action buckets zero-plan exit-0 runs as config-error and fails them under the default policy.

Web and desktop apps

Testing localhost doesn't work in the web app. The web app uses the cloud engine, which cannot reach your machine. Use the desktop app or the CLI in-process engine for local targets.

A fix shipped but the web app still misbehaves. The SPA shows a "New version available — Reload" prompt when it detects a newer build; hard-reload the tab to pick up a shipped fix.

The desktop app isn't updating. The app checks a release manifest and prompts when a newer build is available — accept the prompt to update.