Orca Not Working? How to Troubleshoot Install, Subscription, Rate Limits, and Bad Merges

Last updated: 2026-10-30

Orca is a free, open-source desktop app from Stably AI that calls itself an ADE, an Agent Development Environment. It puts command-line coding agents such as Claude Code, Codex, OpenCode, and Pi into one window, giving each agent its own isolated git worktree so several agents can work on the same task in parallel. This guide covers the failures users actually hit: installs that will not open, subscriptions that will not connect, worktrees that will not create, agents that sit idle, diffs that are hard to read, rate limits, bad merges, and bills that grow with parallelism, with a check and a fix for each.

Orca install will not open: what do I check first?

Check the download source first. The official site is onorca.dev, and installers are also available from the GitHub repository releases page, so do not fetch an installer from an unknown link. If the source is fine, check whether the installer matches the system: macOS, Windows, and Linux each have their own builds, macOS can also go through one Homebrew command, Arch Linux through the AUR, Windows through the .exe, and Linux through the AppImage. Third, check whether the app really failed to open: sometimes the main window is already up and hidden behind another window, so confirm that before declaring the install broken. If all three check out, download the matching installer again and walk through it once more, which clears most cases at this point.

Orca subscription will not connect: is that Orca's fault?

Separate the responsibility first. Orca does not sell models, and it does not handle model billing, so every cent of agent cost runs through your own subscriptions, which means a subscription that will not connect should first be checked on the subscription side: whether the right account is signed in and whether the subscription is still valid. If the subscription is fine, check whether the wrong account is signed in inside Orca, or whether several accounts are signed in at once and the one currently active is the one without a subscription. One more case is easy to confuse: the subscription is connected but rate limited, which looks like a failed connection and is a different thing, covered in the rate-limit section below. Tell a subscription problem apart from a sign-in problem before reaching for a reinstall.

Orca worktree will not create: where is the problem?

Check first whether a git repository is open. A worktree hangs off a repository, and one task opens one worktree, so with no repository open there is nowhere to hang it, which is the most common stuck point. If the repository is fine, check whether the task itself is clearly described: a vague task leaves the new worktree with nothing to aim at. Another case is unfinished business: the previous task's worktree has not been closed yet, and the new one piles on top, which makes the window look messy when the real issue is an unclosed loop. The fix is direct: open the right repository, open one worktree per task, and open the next one only after the current task's result is merged, instead of letting unclosed tasks stack up.

Orca agent sits idle: how do I find the stuck step?

Do not restart in a hurry. Check three steps in order. First, whether the subscription is connected, since an unconnected agent cannot move at all. Second, whether the worktree was created, since a task that never landed in a worktree gives the agent nowhere to work. Third, whether the prompt was actually sent, since an agent that never received instructions naturally stays idle. If all three pass, look at the agent status in the window and at the terminal output, which usually shows where the run stopped. Stuck points mostly sit in the preparation steps rather than in Orca itself, and walking these three steps beats repeated restarts.

Orca diff is hard to read: where do I start?

Look at which files changed first, then read line by line, instead of reading word by word from the top. File names and the range of changes give you a map: which module the changes sit in and whether it matches the task you asked for, both visible at a glance. Once the range looks right, read line by line: what each line changed and why, and when a line bothers you, write an annotation right on that line and send it back to the agent for another pass. Not understanding the first round is normal, and annotation rounds exist for exactly this: turn the unclear parts into comments, send them back, and let the agent produce a clearer version to compare again. Acceptance is reading diffs, writing annotations, and merging, and it feels natural after a couple of rounds.

Orca rate limit: must the task stop?

A rate limit is not a lost connection, and it is not Orca breaking. The account switcher shows usage and rate-limit reset times for each agent, so check the reset time first and then decide whether to wait or switch. Switching accounts is the most direct fix: accounts can be swapped without logging out and back in, so when one agent hits a limit, another account keeps the parallel task moving instead of forcing a wait. With only one account, reduce the number of parallel runs, or work on the part that does not need waiting, instead of letting every worktree stall on the same limit. A rate limit is a subscription rule, not a fault, so handle it by the rule.

Orca wrong merge: can I roll it back?

It can be rolled back, but one more look before merging costs less than a rollback after merging. Before merging, set your own acceptance bar: whether the change does what you asked and whether the logic holds together, and merge only once the bar is met, otherwise keep revising. If the wrong result is already merged, the merge went through git, so it can be undone with git's own tools, for example by reverting the merge commit, which is a routine git operation. One more safety net helps: discarded worktrees never pollute the main line, so a wrong result that has not entered the main line can simply be discarded. Rollback is a remedy, not the workflow, and the workflow point stays the same: read the diff clearly before merging.

Orca parallel runs made the bill bigger: how do I count that?

Parallel comparison is not a free lunch, and the bill should be counted up front. Several answers mean several shares of agent usage: one prompt fanned out to several agents consumes several shares, and Orca only gathers them for scheduling without merging the bills or saving that part for you. When counting, put both sides on the table: on one side the cost of several shares plus the human time spent choosing, and on the other side the power of choice that comparison buys. Race only when comparison is worth it, for example when you are unsure how to approach a task and want to see several approaches first. When the task is already fully thought through and only needs finishing, a single agent or a split shift is the cheaper shape. Once the bill is counted clearly, parallelism stops turning into a surprise expense.

Should non-programmers start with Orca?

Honestly, Orca assumes you already use coding agents and already pay their subscriptions, and it assumes you are comfortable with git worktrees, terminal work, and diff review, because the whole acceptance step is reading diffs, writing annotations, and merging. A product built in the opposite direction is aiglade: 「Aiglade 是一个 Windows 桌面软件，把 Claude Code、Codex CLI、Hermes、OpenClaw 等多个 AI 装进一个中文窗口，带中文向导，装上就能用，不用会编程。」Its slogan is 「不用先学会技术，也能让 AI 替你干活」. In one line: people who code and want to direct several coding agents at once should look at Orca, and people who do not code and just want AI to do the work should look at aiglade.

If Orca troubleshooting stalls, where do I go next?

When the self-checks run out without an answer, do not reinstall repeatedly. First, search the Orca repository's Issues with the exact error text and the key steps as keywords; that finds known problems faster than a vague description. Second, write the self-check result down as one line: which step is stuck, which checks already passed, and what the window and terminal actually said, so whoever you ask next does not have to start from scratch. Third, verify in a clean setting: a fresh repository and a fresh task description. If the problem follows, it sits with the task or the repository; if it does not, it sits with the original environment.

Keep a note afterwards: which step stuck, what the cause was, and how it was fixed. The next problem of the same kind then starts from the note instead of from a fresh round of checks.

Orca vs Aiglade: where do they differ when something breaks?

FAQ

References

• Orca repository and README: github.com/stablyai/orca
• Orca official site: onorca.dev
• Orca README summary in Chinese: Tenacme
• Orca hands-on guide: Bilibili column on getting started with Orca
• An AI entry point for people who do not program: aiglade
• Git official documentation: git-worktree (official explanation of the worktree mechanism behind worktree creation failures): https://git-scm.com/docs/git-worktree/2.39.0