Appearance
Common failure signatures
When a task or an upgrade stops, the reason is usually written in plain words on the task, the issue or the script output. This page maps the common sentences to what they mean and what to do. The exact wording comes from the code; if you see a sentence not listed here, search the repository for it.
A task is blocked or failed
| What you see | What it means | What to do |
|---|---|---|
no commit after 3 attempts | The agent ended three runs without a commit. | Read the session log; fix the brief or scope, then move the card back to Ready. |
planning stopped after three failed starts | Planning failed to start three times; the task is failed. | Check runner health and the model gateway, then start planning again. |
write outside allowed paths: `path` | The agent tried to write outside the task's Scope. | Widen the Scope on the card (signed approval) if the path is right. |
local gate `name` failed after 3 attempts | A gate failed on three agent attempts before publish. | Read the gate output on the task. The fix is usually in the code or the gate, not the platform. |
main moved 3 times while the gates ran; the agent's work is kept and can be retried | The base branch moved on each gate run (MaxBaseMoves). | Retry once main is quiet. The work is kept. |
running exceeded 120 minutes across 3 attempts (or a gates variant) | The total time budget is spent (actor time-budget). | Look at why the sessions were slow; retry or split the task. |
could not finish gates after 5 attempts | Delivery of gate results failed five resumes. | Check the runner and its evidence key. |
could not resolve the publish conflict after 5 attempts | Publishing kept conflicting after repairs. | A person resolves the conflict, or retry after main settles. |
Task blocked after GitHub was unavailable (agent-publish-blocked) | Three signed-publish attempts met a GitHub outage. Work is kept. | Check GitHub status and the GitHub App, then retry. |
review fix stopped after three runner attempts; PR remains at the reviewed commit | A review fix failed three times. | Fix the PR by hand, or move the card back to Ready to retry the fix. |
review still blocking after N fix rounds | Review kept blocking after the allowed rounds. | A person decides: fix by hand or cancel. |
workspace limit reached: ... | A monthly cap on model tokens or sandbox minutes parked the task. | Raise the cap in the app (PUT /v1/usage/caps, administrators). |
The platform is not moving
| What you see | What it means | What to do |
|---|---|---|
| Jobs queued, no runner claims them | No runner registered, or none has checked in for 5 minutes. | Open the instance health page (GET /v1/instance-health); restart the runner; check its certificate has not expired. |
| New tasks for a repository are held | The repository's main branch fails a gate in the sandbox. | See GET /v1/main-health; fix main first. |
| Intake creates nothing | A pin is missing or wrong (UNSET or mismatch), or the kill switch is on. | Check the repository's agent pins and the kill switch state. |
sandbox network must be an internal isolated Docker bridge | The job network is not an internal bridge, or has an unexpected peer. | Recreate the job network and proxy; never attach other containers to it. |
| A runner is refused evidence | Its evidence key is not approved, or was rotated or revoked. | List keys (GET /v1/runner-keys) and enroll the right one. |
unsupported version or invalid lease from the runner API | Runner and control plane are on different builds, or the lease expired. | Upgrade them together. A stale lease token cannot renew. |
An upgrade stops
| What you see | What it means | What to do |
|---|---|---|
a task is claimed or running (or the database could not be asked) | upgrade.sh refuses while work is active. | Wait for tasks to finish, or check the Postgres container is up. See Restarts and leases. |
could not fetch the target commit from origin | The checkout's remote credentials are stale. | Export a fresh GH_TOKEN. |
the new build rejects the intake configuration | The config check against the new image failed. Nothing was changed. | Fix the configuration named in the error. |
could not read the shared runner key | Step 6 needs the old shared key. | Check FORELEAD_SECRETS_DIR, or set LEGACY_RUNNER_KEY_FILE. |
FAIL: runners left stopped | The upgrade failed after stopping the runners. | Fix the item above it, then run deploy/upgrade.sh again. After the migration step do not restart the old image: it refuses a newer schema. |
runner certificate maintenance failed | The runner certificate renewal failed. The old pair is restored. | Inspect the systemd journal. See Certificates. |
Technical notes
- Every behaviour, with the test that proves it, is in Task failure contract.
- Block reasons are appended as
task_transitionsrows with an actor (for exampletime-budget,agent-base-moved-blocked,agent-publish-blocked), so the task timeline shows who stopped it. - Cap parking uses the reason prefix
records.CapReasonPrefix.