Tasks fail. Most failures are configuration or specification problems rather than anything mysterious, and they fall into a small number of shapes.
First, read where it stopped
The run shows which stage failed. That single fact narrows the cause more than anything else:
| Failed at | Almost always means |
|---|---|
| Before any code was written | Build or install command wrong for a clean workspace |
| While making the change | Genuinely hard work, or a missing dependency |
| Running tests | Test command wrong, or the suite needs a service |
| Verification | A blocking gate; check the findings |
| Review | Findings that could not be auto-fixed |
Failures before the change is written are configuration. See Build and test configuration.
- Where it stopped
- Running tests. The suite needs a database that the clean workspace does not have.
- What to change
- The project's build and test configuration. Retrying the task unchanged fails the same way.
It is not stuck, it is queued
A task in PENDING is not stuck. It is waiting for a free agent slot. Check
capacity before anything else — this is the
most common false alarm.
It is asking you something
NEEDS_HUMAN_REVIEW means the task hit a decision only you can make. It is not a
failure. Answer the question and it continues from where it paused.
Answer precisely. A vague answer produces another guess and another pause.
Running much longer than expected
Two usual causes:
A slow or hanging test suite. Coroid runs your suite; if it hangs in a clean workspace, the task waits. Reproduce by running the suite against a fresh clone.
A specification broad enough that the agent keeps finding more to do. The tell is a growing file list. Cancel, tighten the scope with an explicit out-of-scope line, and re-run. See Specifications.
Choosing what to do
In increasing cost:
- Answer — for
NEEDS_HUMAN_REVIEW. Cheapest, keeps all context. - Rework — the work is right but incomplete. Goes back to the developer agent with your findings and its context intact.
- Pause — you need to check something first. Frees the slot; resumable.
- Retry — for genuinely transient failures only. Retrying a configuration problem just reproduces it.
- Cancel and re-specify — the approach or the scope was wrong. Most expensive, and often the right call.
Answer
For a question. Keeps all context.
Rework
Right but incomplete. Goes back with your findings.
Pause
You need to check something. Frees the slot.
Retry
Only for genuinely transient failures.
Cancel and re-specify
The approach or scope was wrong.
Failures that repeat across tasks
The same failure at the same stage on unrelated tasks is a project configuration problem, not a task problem. Stop re-running tasks and fix the configuration.
A release is blocked after the task is done
A completed task means its work reached review; it says nothing about the selected release commit or deployment. On the Release page, select the environment and read the gate blockers. Re-evaluate after completing the checklist or when a Quality Graph run finishes. A changed SHA, scope, or policy makes the old gate and approvals stale. If a deployment is already running or its outcome is uncertain, inspect the provider run before requesting another one.