Troubleshooting
The failures that look like bugs but are usually configuration.
A worker polls but never claims anything
Section titled “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
Section titled “A worker is registered but one project stays idle”Registration assigns projects; it does not approve a filesystem. The repository path an administrator set for that project also has to be allowed on the worker’s own machine. Until it is, that assignment stays unbound and the fleet console shows the reason — the worker’s other projects keep running normally.
The PM agent pages are empty or say it is not configured
Section titled “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
Section titled “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
Section titled “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
Section titled “The dashboard’s difficulty panel is empty”It reads a custom field named exactly Difficulty. Create it as a dropdown in Settings → Task fields, and the panel fills in as tasks get values.
A custom field’s value shows as a dash
Section titled “A custom field’s value shows as a dash”Dropdown and multi-select 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.
Someone cannot see a project
Section titled “Someone cannot see a project”Members see only the projects on their allowed list, and everything follows from it — sidebar, search, My tasks and API responses alike. Grant access in Settings → Users.
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
Section titled “Notifications arrive in the app but not by email”Email needs both halves: SMTP configured on the instance, and the individual opting in under Settings → Preferences. Slack and Discord are separate again, and set per project in Settings → Integrations.
A dependency will not save
Section titled “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.