Troubleshooting

Start at the status page: the main status card’s headline says what state you are in, and anything waiting on you is listed under Needs your attention with the button that fixes it. Almost every failure state in Orbi Cloud is self-describing. This page covers what each one means and what to do, in roughly the order people hit them.

​

I do not know what to do next

Look at the setup checklist on the status page for the step waiting on you. Videos are available for installing the App, connecting a repository and writing the first request. The quickstart covers the complete path in writing. Once the environment is ready, Orbi reads the repository for suggestions, usually in about 2 minutes. You can leave while it reads. For a new task, Review draft and confirm before handing it off; for an existing Issue, Let Orbi do this dispatches immediately. With no suggestions, use Get suggestions, or Write a request directly. See your first Issue and write a request.

​

Nothing happens after I label an Issue

Work through this list, in order:

1. Does the Issue actually carry ai-ready? This is the most common cause. Writing the Issue is not enough; the label is what starts the work. Check the Issue’s labels on GitHub. The status page’s Let Orbi do this button and the write-a-request page’s Hand off to Orbi add the label for you.
2. Is it in a connected repository? Orbi only reads Issues in the repositories you connected. Check the project overview on the status page.
3. Is the work environment ready? Prepare work environment in the setup checklist must show Done. Until then there is nothing to run the delivery.
4. Has five minutes passed? Adding the label usually wakes Orbi within a minute; the five-minute timer is the fallback.
5. Did the label come back off, with a comment? Your free deliveries are used up — see limits and quotas. Subscribe, then re-apply the label.
6. Does the page say Monthly AI usage is used up; new tasks are paused? New Issues wait until the allowance resets, or until you add your own model key. The labels stay. See limits and quotas.
7. Does the page say A task is not in the current version and will not start yet? A current version (delivery scope) is set, and your Issue is not in that version’s milestone. Move it into the version, or switch the current version. See releases.
8. Does the Issue already carry another ai-* label? An Issue that is already ai-in-progress or ai-merged is not re-dispatched by adding ai-ready again.

If work environment preparation failed, read the main card and Usage and settings → Connected projects.

​

ai-blocked

ai-blocked is a deliberate stop, not a crash. It means automatic recovery was not safe, and a person has to decide the next step. The status page says Orbi is stuck and needs you and names the Issue. Read the comment Orbi left on the Issue. It states why it could not proceed. When Orbi recorded a reason, the card on the status page sums it up in one sentence and its See Orbi’s note button opens that comment; otherwise the button is View on GitHub (Issue #N). The common causes:

• The repair loop ran its rounds without reaching a clean review verdict.
• An external precondition is missing — something the delivery cannot safely judge or fix on its own.
• A release’s milestone does not exist. The status page offers Create the version and continue for this one.
• The Issue asks for something the environment cannot do (see below).

How to recover: fix the underlying cause first, then swap the label. If the Issue already has a pull request, replace ai-blocked with ai-fix-needed: Orbi picks up the same pull request again with a fresh review budget. If there is no pull request yet, replace ai-blocked with ai-ready. Fixing the cause often means editing the Issue — sharpening the acceptance criteria, removing an impossible requirement, or splitting it into smaller Issues. The pull request, branch and workspace are all preserved when an Issue blocks, so nothing you have is lost.

​

Acceptance criteria the environment cannot satisfy

A frequent cause of a blocked Issue is asking for evidence that cannot exist inside the delivery environment. That environment has your repository and your tests — it does not have your production credentials, your third-party accounts, a real browser against your live site, or your deployment pipeline. An Issue whose acceptance requires “deploy to production and confirm”, “log in to the live dashboard and screenshot it”, or “reproduce against the real expired token” will spin and then block. Rewrite the criterion as something checkable in the repository — assert the rendered text in a test, assert the error classification, assert the thing that must not appear — and gather the production evidence yourself.

​

Orbi needs more information

The task shows Needs detail (ai-needs-detail), and the status page shows a card saying the request is missing information: what users will see change once it is done, how to tell it is done, and one change per request. Click Add the details. That opens the write-a-request page; what you settle there is added to the Issue body, and the Issue goes back to ai-ready on its own. You can also do it on GitHub: add what is missing to the Issue body, then re-apply ai-ready. Orbi re-reads the Issue body when it picks the Issue up again, so a reply in a comment alone is not enough.

​

When Orbi has already proposed a fix

Sometimes Orbi’s comment already contains a proposal, and the card on the status page shows it:

• Orbi suggests splitting this ticket into N tickets lists one line per child ticket, each with its acceptance line. Split it like this creates those tickets; each is built and merged on its own. This Issue becomes the parent and closes once every child ticket is done.
• Orbi drafted the acceptance criteria lists conditions Orbi drafted from your description. Start with these adds them to this Issue, and Orbi starts.

Edit opens the proposal inside the card. Save changes only edits Orbi’s proposal comment on GitHub: it creates no tickets and starts nothing, so press the start button afterwards. The start button posts /orbi split or /orbi amend on the Issue under your own GitHub account, so you need write access to the repository; replying with that command on GitHub yourself does the same. The card then says Submitted — Orbi is working on it, usually for a minute or two. If the card still says Submitted after a few minutes, open the Issue and read Orbi’s receipt for the command: when Orbi did not run it, the receipt gives the reason. Fix Orbi’s proposal comment on GitHub accordingly, then comment the same command (/orbi split or /orbi amend) on the Issue again.

​

The configured base branch no longer exists

Open Manage projects → Change base branch, select an existing branch and Save base branch. For an Issue blocked by that missing branch, Orbi queues it again automatically, usually within 1–2 minutes. Do not disconnect and recreate the project or change labels just to apply this repair. See changing the base branch.

​

Checks on the base branch itself are failing

When a check fails both on Orbi’s reviewed pull request and on the base branch itself, the pull request cannot fix it, so Orbi pauses the delivery in ai-blocked instead of merging. The status page card says the change is written, reviewed and tested, and lists the base branch’s failing checks by name. Click Have Orbi file the fix tickets. Orbi files one fix ticket per failing check and queues it, and the card says Submitted — Orbi is filing the fix tickets. Once the base branch is green, Orbi resumes the original task on its own, with no label change from you; it still merges only after review, CI and branch protection pass, and still waits for approval if the repository requires one. Fixing the base branch yourself works just as well. The button posts /orbi fix-base under your own GitHub account, so it needs write access to the repository. If the base branch is still failing after seven days, Orbi posts one reminder and stops watching; once it is green, replace ai-blocked with ai-fix-needed yourself.

​

Telegram messages are missing

Check Settings → Notifications: it must be on, with the saved Chat ID and a bot allowed to post. Request a test and check Telegram after 1–2 minutes. Configuration changes can take 1–10 minutes. Notification failures do not change the task result; read GitHub or the status page meanwhile. See notification troubleshooting.

​

The pull request is waiting for my approval

The headline says You need to approve this change on GitHub, and the task shows Awaiting approval. Your branch protection requires an approving review, which Orbi cannot give itself. Approve the pull request, or change the rule — see branch protection.

​

The pull request looks wrong

Comment on the Issue with the correction, or edit the Issue body. A running delivery picks it up and restarts with your correction — you do not need to close anything or cancel. See steering a delivery. If the work is simply not wanted, close the Issue. If it was a free delivery, closing it without a merge refunds the slot.

​

Provisioning failed

The main status card says whether it needs you, is retrying, or is being recovered by the platform, and View failure reasons and repair steps takes you to Usage and settings → Connected projects, which shows the reason, the time, an Error ID and the next step. There are four classes, covered in full on the provisioning page: Quote the Error ID if you contact support. The support email link next to it puts the Error ID in the subject for you.

​

I cannot connect my repository

Full detail is on connect a repository.

​

GitHub asks me to approve new permissions

When Orbi’s GitHub App adds a permission, GitHub does not grant it to existing installations until the account owner approves it. Until then, Orbi cannot read some of your repository’s state (for example the status of CI checks), so pull requests can stay open without merging. To approve: on GitHub open Settings → Applications → Installed GitHub Apps, click Configure next to Orbi, and accept the pending permission request shown there. For an organization, an owner does this under the organization’s Settings → Third-party Access → GitHub Apps. GitHub also notifies the owner about the request (GitHub docs). If a pull request still does not move afterwards, see getting help.

​

The GitHub App was uninstalled

The status page detects this and says Orbi’s GitHub App was uninstalled. Reinstall it to continue., offering Reinstall the Orbi GitHub App. Reinstalling on the same account reconnects to your existing tenant — your history and settings are intact. You may need to reconnect the repository afterwards.

​

Issues got disabled on my repository

If the Issues feature is turned off after connecting, the status page says so. Re-enable Settings → Features → Issues — Orbi’s entire input channel is Issues, so nothing can run without it.

​

My quota is draining faster than expected

Open Usage and settings and check the Cached percentage on the Monthly AI usage line. Cached tokens count toward the allowance the same as input and output tokens, so the cached share does not change how fast the allowance is used; a fast-draining allowance means the tasks themselves use a lot of tokens. The usage line under each task in Task history shows which deliveries were expensive. Large, vague Issues cost far more than small, specific ones — both in tokens and in repair rounds.

​

A task shows no usage

If a task in Task history has no usage line, that work item never reported usage statistics. It is a gap in measurement, not a sign the delivery failed. The Monthly AI usage line notes how many such tasks are left out of the total.

​

My session expired

Sign in again. Nothing is lost: your repository connections, model configuration and task history belong to your tenant, not to the browser session.

​

The page is in the wrong language

Open the account menu (your avatar, top right) and choose 🇨🇳 ZH or 🇺🇸 EN. On the sign-in page, the same switch is in the top right. The choice is stored for a year on that browser.

​

Getting help

Use Get support on Telegram in the avatar menu or footer, email [email protected] for account and billing matters, or use Book 15 min with the founder ↗ on the help line. The status page, the connect page and the write-a-request page also have a support chat window in the bottom-right corner. These are support channels; they are separate from your bot notifications. Include the account, repository, Issue or PR link, error ID if shown, and approximate time with its time zone. Do not include API keys, bot tokens, GitHub tokens or private code in a public chat. A documentation mismatch can also be reported in the public docs repository.