Build and run / Harnesses

Troubleshoot a harness

Updated 28 Oct 20264 min read

Start from the task. Its Journey shows every rule that was checked and why it did or didn't match, and What it did shows every action its runs took.

A task isn't moving

What you seeWhat it meansWhat to do
The task waits in a stage with Waiting on SystemThe stage waits for an event, such as a mergeCheck that the task has a linked pull request or ticket, and that the repository webhook is set up (see below). The stage's timeout moves it on otherwise.
The task waits with Waiting on HumanA bot asked a person and is waiting for the answerAnswer in the bot's conversation (Optimus Worker on the task), or approve under Tool approvals
The task is assigned to a personBots stop working a task a person ownsHand it back to the agent
The harness is pausedNothing new runsResume or Enable it on the Harnesses page
The harness has reached its monthly budgetNew runs waitRaise the budget in the template, or wait for the new month
The journey shows max_visitsThe task looped as often as allowed and went to a personDecide in the escalation stage

A finding says "Waiting for the next group"

The harness groups findings, and this one missed its group, for example because it arrived after the group was formed or wasn't fixed last round. It joins the next group. To work it now, group it with others yourself, or ask Optimus to.

I can't change a bot's schedule

The bot is a scheduled input or watcher of a harness that is switched on, and the harness owns its schedule. Change the schedule in the harness (Edit in Optimus), or pause the harness first.

Nothing arrives from my repository

  1. Open VCS webhook setup on the Harnesses page.
  2. Add the URL and secret to your repository's webhook settings, with the events the page lists.
  3. Make sure the fix bot links its pull request on the task. The harness only sends an event to a task that carries the matching link.

A tool call was refused

The bot's conversation shows a message starting with [harness policy: ...]:

MessageMeaning
needs_approvalThe tool needs a person. Approve it under Tool approvals on the task.
denyThe harness policy or the harness type never allows this tool.
shadowThe harness is in shadow; the call was saved as a draft.
the harness policy could not be checked right nowThe platform couldn't check the rules for a moment, so a call that would change something was refused. The bot can retry.

Apply draft was stopped by preflight

Applying a change runs Preflight first. When a check fails, the apply is stopped and the failing checks are listed with the bot each one concerns, for example a bot that was deleted or turned off, or an account that no longer works. Fix what the check names and apply again. Force apply applies anyway; the failing checks stay failing, so the harness may break when it next reaches that bot.

I can't arm or delete a harness

  • Shadow and active need an applied template. Apply the pending change first.
  • Delete needs a stopped harness. A harness in shadow or active is still routing work; set its State to Disarmed, then delete it.
  • Making a harness active, resuming it and applying changes to one that has run before are done by a person. Optimus can only start a new harness in shadow, or pause or disarm one.

A test event didn't create a task

The event view lists the tasks an event created or updated as they appear; routing runs in the background, so give it a moment. If none appears, the event may have matched an existing task (it shows as updated), been suppressed as a known false positive, or been dropped by the harness's intake rules. Open a task's Journey to see which rules were checked.

A bot run timed out

Each bot has a time limit for one step of work. Bots that clone, scan, build or test need a larger job size than ones that only call APIs. Ask Optimus to check the bot's job size and time limit, and to raise them if the work needs it.

A finding was closed but isn't fixed

Check the group's verify stage: each finding closes only on its own result, and the verify bot has the last word. If a harness has no verify stage, ask Optimus to add one. If it reappears in a later scan within the reopen window, its task reopens.

Next steps

Need a hand with this?Our engineers can walk through it with you on your own stack.