Troubleshooting

The failures that look like bugs but are usually configuration. Getting an instance to start, sign in and connect a machine in the first place has its own table, in Installing and running.

The screen says “Something went wrong”

That is the app’s error screen, shown when a page fails in a way it cannot recover from. Copy details puts the failure on your clipboard — the message, the digest Next.js assigns it, and the stack — which is what to paste into a bug report. If the failure carried none of those, the copy says so rather than handing you an empty string.

Reloading is worth trying once: a page that failed on a transient error usually comes back. A page that fails the same way twice is a bug, and the copied details are the useful half of reporting it.

Caution

The details include a stack trace from the server. On a self-hosted instance that is your own code and your own paths — but treat what you paste into a public issue tracker accordingly.

I handed a task to an agent and nothing happens

Open the task. Under the Agent row it lists everything that is stopping it — the task’s own requirements and the board’s — and names who can fix each: an unfinished blocker, the board naming no repository, agent runs being off for the board or locked off by an instance admin, a column role the board is missing, or, on your own task, no machine of yours with the board’s repository checked out, or one that is silent, paused, stopped, failing its sandbox check, or, from 1.1.2, refusing its checkout of this board — with what is wrong with the checkout and what to do about it; and a task machines have already tried as many times as they may. Once nothing is missing, it says Waiting for your machine to take it instead. See the Agent row.

If it says it is waiting and nothing comes, the machine itself is the place to look: the sections below.

A worker polls but never claims anything

Workers claim from columns whose role is approved — not from a column called “To Do”. If the project’s columns were renamed or rebuilt and none carries that role, there is nothing to claim.

Check Settings → Board and confirm exactly one column has the approved role. Two columns with it means the worker claims from both, which is rarely what anyone intended.

A worker is registered but one project stays idle

A worker is only offered a project when two things are true: the project is enabled for workers in its own settings and not locked off by an instance administrator, and that machine has reported a checkout whose origin matches the project’s repository.

Check both. An instance administrator sees the machine listed under “Machines offering this repository” in Project settings → Workers — if it is not there, the checkout is missing from repos.json on that machine, or the project names a different repository under Integrations. The fleet console shows the reason against the worker, and its other projects keep running normally.

That list is only shown to instance administrators. As a project owner, open Settings → Workers → your machine → Projects instead: it lists every project your machine can reach, marks the ones it already serves as connected, and says so when a project is switched off or locked off by an instance administrator. A locked project shows a red banner at the top of its own Workers section.

A repository reachable at two different hosts does not match: git.internal.example.com/owner/repo and github.com/owner/repo are treated as different repositories, deliberately. A per-account ssh alias such as git@github-you:owner/repo.git does match, because the alias is only meaningful on that machine.

I ticked a project and no checkout appeared, or I unticked one and it is still there

Saving on the picker records what you want; the menubar app acts on it the next time it connects to the worker — on app start, on a worker restart, or when a dropped socket comes back. If the app has been connected the whole time, it has not looked again yet.

There is a second reason, and for an untick it is the usual one: the app asks on the machine before it deletes anything, and that dialog is waiting for somebody. Go to the Mac holding the checkout. The unticking stands until it is answered, so nothing is lost by leaving it — the app asks again each time it connects.

An unanswered dialog can hold up a tick too, but only one saved after the dialog appeared: what you save while it is up is not acted on until it is answered. A tick saved in the same breath as the untick is not affected — clones run before any deletion is proposed. One trip to the machine clears whatever is waiting.

A third reason, and the one to check first on a machine that has never cloned anything: the app has no checkouts folder. It has nowhere to put a clone, so it does nothing — and it now says so. Preferences → Repositories names the projects it could not act on, and points at the setup screen’s Where it keeps its checkouts, which is the one place that folder is chosen. Choose one and the next connection clones them.

If the dialog was answered with Keep, or a guard refused, Preferences → Repositories says so by name — one line per attempt, so a project declined twice appears twice.

Two workers on one machine and one of them never claims

Two worker processes must not share a working tree. When both report the same path, the one that registered first keeps it; the other is told which machine holds the checkout and leaves that project alone. Give the second process its own checkout, or stop it.

The PM agent pages are empty or say it is not configured

The PM agent needs OPENROUTER_API_KEY on the instance. Without it the feature is inert by design.

If the key is set and a single project’s agent is still off, check two switches: Settings → PM agent on the project, and the instance lock in Settings → PM Agents. An instance administrator can lock an agent off in a way project settings cannot override.

If the agent worked earlier today and stopped, it has probably spent its turns per day. Autonomous reviews draw on the same budget as your chat.

AI Assist is missing from the task form

That box appears only when OPENAI_API_KEY is configured. It is a different key from the PM agent’s — setting OPENROUTER_API_KEY does not enable it.

A pull request is not showing on its task

Pull requests are matched by task key in the branch name or the title — ORB-14, case-insensitive. A branch called feature/invoice-preview matches nothing. Check that the project has a repository and token set in Settings → Integrations.

The dashboard’s difficulty panel is empty

It reads a custom field named exactly Difficulty. Create it as a Choice field in Settings → Task fields, and the panel fills in as tasks get values.

A custom field’s value shows as a dash

Choice and Multi-choice values have to be one of the field’s configured options. A value that no longer matches any option renders as empty rather than as stale text — the history is kept, but the badge is not drawn. Re-pick the value, or restore the option.

A screen says it failed to load

The read behind that screen did not answer, so nothing about the data follows from it — the screen is not telling you the list is empty, and it is not telling you anything was deleted. That is why it says so instead of drawing an empty state. Retry asks again in place; there is no need to reload the page.

An instance whose database is unreachable usually shows a band across the top as well — or, if the app has not yet worked out who you are, a page saying so, with its own Try again now. That page does not mean you were signed out; it keeps trying and comes back on its own. One screen failing while the rest of the app works is more often a single slow request, and a Retry is all it needs. A refusal is different: it says so in words and offers no Retry — see Someone cannot see a project.

Several screens used to answer a failed read with a sentence about the data instead, and two were worth naming. Settings → Email said No mail server is configured when it had simply failed to read the settings — take that as an instruction to set SMTP_HOST and restart only when the page is actually showing you the configuration. An agent’s page said No agent with that id, which reads as deleted; it now says it could not read the agents catalog, which is all a failed read knows.

The Agents pages say what they show may be out of date

A change was saved, and the read that would have refreshed the catalog afterwards failed. What is on screen is what was there before the change — the save itself went through, which is why the catalog is kept rather than replaced by a failure. Retry re-reads it. The banner appears on the Agents screen and on an individual agent’s page alike.

The banner needs something to keep: on a screen that had nothing on it yet, the same failure fills the screen instead. The band across the top uses similar words for something wider — any request that answered with a server error, or did not answer at all — a save as readily as a read — and it can be up at the same time as this banner, since the refresh that failed is one of those requests.

Someone cannot see a project

Members see only the projects they have been let into, and everything follows from it — sidebar, search, My tasks and API responses alike.

Opening such a board by its address says You do not have access to this board. — on the board, its sprints, its settings, its dashboard, its PM page and any of its tasks alike — and offers no Retry, because asking again gets the same answer. To an instance administrator, an address naming no board at all says There is no board here — the link may be stale. instead. Anybody else gets the refusal for a missing board too, on purpose: telling the two apart would let an address reveal which boards exist. On a board you can open, a task that does not exist says There is no task here — the link may be stale.

A board whose access is taken away while it is open is replaced by the same sentence at its next refresh, and an open task says so the next time it saves. The board keeps checking once a minute, so if access is given back it returns on its own; reloading the page brings it back at once.

Access is granted from the project, not from the user list: open that project’s Settings → General and give the person Member or Owner. Creating the account under Settings → Users grants nothing on its own, which is the usual cause — the account exists and sees an empty sidebar.

If it is a token rather than a person, remember a scoped token is limited to the projects chosen when it was created, and it can never exceed what its owner may see.

Notifications arrive in the app but not by email

Email needs both halves: SMTP configured on the instance, and the individual ticking the E-mail column for that event on Settings → Notifications. There is no e-mail control on Preferences. Slack and Discord are separate again, and set per project in Settings → Integrations.

A dependency will not save

Dependencies that would create a cycle are refused — directly, or through a chain of tasks. If A blocks B and B blocks C, then C cannot block A.