Orca

Troubleshooting & FAQ

Agent won't start

  • Run the agent's CLI in a regular terminal outside Orca. If it fails there too, check the CLI installation and login. If it fails only in Orca, check the guidance below.
  • Make sure the CLI is on the PATH Orca sees (check Settings → Agents).
  • Try the Restart chip on the tab.

Codex reports path must be shorter than SUN_LEN

Update Orca to v1.4.212 or later. Codex 0.157 and later can hit this error when the background daemon's socket path is too long in an Orca-managed account home. Orca now adjusts affected homes automatically; you do not need to move the account or edit your system ~/.codex/config.toml. See Codex in Orca.

Orca asks which profile copy to use

If both the JSON and SQLite copies of your profile are readable but disagree, Orca shows when each was last saved. Choose Use SQLite (Recommended) or Use JSON to keep that copy; Orca applies your choice and restarts. Choose Quit if you need to inspect the copies first. Other profile recovery errors can still show separate command guidance.

Diff view looks wrong / stuck

  • Click the refresh icon on the diff toolbar — Orca re-reads the worktree.
  • External git operations (rebase, reset) can land between refreshes.

Worktree creation fails

  • The start-from ref may not be fetched. Open a terminal in the repo and run git fetch origin.
  • The target directory may already have a worktree for that branch — delete it or pick a new branch name.

Orca CLI says "command not found"

Register the CLI under Settings → General → Orca CLI. On macOS it installs a shim into ~/.local/bin; make sure that's on your shell's PATH. On Windows, orca is a native program the installer adds to your PATH.

SSH connects but remote terminals fail

  • Orca sets up its own managed server on the host, so a wrong Node version or missing build tools no longer blocks the connection. Settings → SSH Hosts says which server a host runs, and Settings → Managed servers can update, roll back, or recover it. See SSH worktrees → Managed Orca server.
  • A host the managed server cannot run on no longer falls back to the old SSH runtime: Settings → SSH Hosts explains why, and the connect fails with that reason. Use an older Orca version to keep connecting to that host.
  • Terminals carried over from v1.4.224 keep accepting input and output, but they do not have the orca CLI. Open a new terminal on the same host for orca commands.

SSH works for files but not “Download Folder”

Folder download needs recursive SFTP transfer. File download may still work on system-SSH-only connections. Use a terminal tar/scp as a fallback.

“Open in VS Code” is disabled or Local only

  • Use an SSH worktree (not a Remote Orca Server active runtime).
  • Set the Open-in command to VS Code / Insiders, not Cursor or a multi-arg shell command.
  • Refresh SSH targets if the host was removed.

Kerberos login fails

  • Ensure klist shows a valid ticket for the host realm.
  • Confirm GSSAPIAuthentication yes for that Host in OpenSSH config, then re-import or re-test the target in Settings → SSH.

Browser says browser_no_tab

No tab is open in the current worktree. Open one with orca tab create --url ... or open the browser pane manually and navigate.

Performance & memory

  • Close worktrees you're not actively using. Each worktree keeps file watchers alive.
  • Split layouts with many browser tabs are the biggest RAM users — close browsers you don't need.

GitHub PR panel / checks / Tasks errors

Rate limits, bad gh auth, missing scopes, and repo access issues all show up in Source Control and the PR Checks panel. See Troubleshooting GitHub errors for the full matrix (including why GitHub API Budget in Settings can look fine while REST is still blocked).

If Orca says the GitHub CLI is not installed even though gh works in your terminal, a gh launcher on your PATH is likely hanging. Orca keeps looking past a stuck launcher and uses the copy that passes its version check, instead of reporting the CLI as missing.

Quick checks:

gh auth status -h github.com
gh api user
gh api rate_limit --jq '.resources.core'

Logs

Help → Open Logs opens the directory with Orca's logs. Attach these when filing a bug.

Reporting issues

  • Help → Send Feedback (in-app) — paste or drag screenshots into the dialog, or pick image files; thumbnails show before you submit. Attach logs when the bug is hard to reproduce.
  • GitHub Issues — bugs and feature requests.
  • Discord — real-time help.