Files
orca/docs/site/content/docs/troubleshooting.mdx
Neil 552e281b1e docs(troubleshooting): explain the first-connect Node download for SSH and WSL (#35875)
The bullet asked users to install Node for a relay that no longer exists.
Orca now brings its own Node; point restricted networks at the download
mirror setting or the offline archive path the error names.
2026-10-29 02:23:56 -07:00

85 lines
5.1 KiB
Plaintext

---
title: Troubleshooting & FAQ
---
## Agent won't start
- Open the terminal and run the agent's CLI manually. If it fails there, it's an auth or install problem in the CLI itself — not Orca.
- Make sure the CLI is on the `PATH` Orca sees (check [Settings → Agents](/docs/settings)).
- Try the **Restart** chip on the tab.
## 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](/docs/settings). On macOS it installs a shim into `~/.local/bin`; make sure that's on your shell's `PATH`.
## SSH connects but remote terminals fail
- On first connect to an SSH host or a WSL distro, Orca installs the Node.js version its server needs there. It downloads it on this computer, or on the host if that fails. If your network blocks nodejs.org, set **Settings → Advanced → Network → Node.js Download Mirror** to a copy of `nodejs.org/dist`, or download the file named in the error on another machine and copy it to the path the error gives on this computer. Then connect again.
- On Linux, install a C/C++ toolchain if terminals never spawn: make, g++/clang++, python3 (see [SSH worktrees](/docs/ssh)).
- Reconnect after installing tools so Orca can reinstall native modules.
## 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, Cursor, or Zed” 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, Cursor, or Zed, not 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.
## Windows: RAM disappears but no app is using it
Orca workloads start many short-lived processes (hooks, `git status` polling, agent CLIs). If a buggy kernel driver keeps a reference to every process that exits, exited processes are never freed: RAM drains into kernel memory that Task Manager can't attribute to any app, and starting new processes gets slower, so Orca often gets blamed.
- **Quick check:** Task Manager → Details → **PID** column. Windows reuses the PIDs of freed processes, so they normally stay in the tens of thousands; PIDs in the hundreds of thousands or more while the process count is normal can indicate exited processes are piling up. A huge **Page Table** in [RAMMap](https://learn.microsoft.com/en-us/sysinternals/downloads/rammap) (normally a few hundred MB) is another sign.
- **One known cause:** the AMD integrated-GPU driver `amdkmdag.sys` (leaked in `31.0.24002.92`, Adrenalin 24.1.1). Check your actual `amdkmdag.sys` version, since OEM packages can be newer by date and still leak. See [#28293](https://github.com/stablyai/orca/issues/28293) for tested versions, check scripts, and workarounds.
- **Fix:** install AMD's own driver (`32.0.21045.5002` tested clean). On a laptop with a MUX switch, Discrete GPU mode also stops the leak (higher power use, shorter battery life). AMD's Auto-Detect can't see the iGPU in that mode, so switch to Hybrid and restart before installing AMD's driver.
- **Reclaim the memory** with **Restart**, not Shut down: with Fast Startup enabled, Shut down preserves kernel state, so the leaked memory survives it.
## 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](/docs/github-errors)** for the full matrix (including why **GitHub API Budget** in Settings can look fine while REST is still blocked).
Quick checks:
```bash
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](#logs) when the bug is hard to reproduce.
- [GitHub Issues](https://github.com/stablyai/orca/issues) — bugs and feature requests.
- [Discord](https://discord.gg/fzjDKHxv8Q) — real-time help.