Troubleshooting
Most problems fall into a small number of categories. This page covers each one with the specific thing to check.
A run failed
Section titled “A run failed”A failed run appears in the change set with a retry action. Retrying continues from the persisted state rather than starting over, so you do not pay twice for work that already succeeded.
The status reason names the cause. Read it before retrying — a retry against an unchanged cause fails the same way.
If the retry fails the same way, the cause is usually outside the agent’s control:
| Symptom | Likely cause |
|---|---|
| Repeated failure at the same step | A specification conflict that needs a decision |
| Failure mentioning permissions | The GitHub App lacks a required scope — see GitHub App installation |
| Failure mentioning a missing input | A provider credential or configuration is absent |
A merge is blocked
Section titled “A merge is blocked”A change set moves to Needs action when it cannot merge. The status reason names the specific problem.
Merge conflict
Section titled “Merge conflict”A pull request conflicts with the default branch. Resolve it on GitHub; the change set returns to the normal flow once the conflict is gone.
Not every pull request is approved
Section titled “Not every pull request is approved”A change set merges only when every pull request in it is approved. Check the count in the change set panel.
The GitHub App lacks permissions
Section titled “The GitHub App lacks permissions”The App needs full access to the repositories it manages, including organisation-level permission to create new ones. A run that needs to create a service repository fails if the App is scoped to selected repositories only.
Check the installation’s repository access and permissions, and re-consent if a permission was revoked. See GitHub App installation for what each permission is for and how to fix a drifted installation.
The workflow looks stuck
Section titled “The workflow looks stuck”A run that is genuinely working publishes live activity continuously. If the feed has been silent for several minutes, check the service badge:
- Awaiting your review — the run is paused on a plan. Open the service thread and approve or steer it.
- Queued — the run is waiting for credits. Top up and it resumes on its own.
- Active with no activity — the agent is likely running a long command. Give it a few minutes before intervening.
The composer is disabled
Section titled “The composer is disabled”The composer locks while the workflow is running, because a message sent mid-run would be interpreted as new work rather than steering.
It unlocks in two situations:
- A plan is awaiting review (steering is the intended interaction)
- The workflow has finished
If the composer is disabled and no workflow is running, the session is archived. Start a new session.
A service is missing from the change set
Section titled “A service is missing from the change set”A service with no changes does not produce a pull request. If the architecture planned a service but the implementation found nothing to change, the change set records it as a no-change service rather than an empty pull request.
Credits are held but nothing is running
Section titled “Credits are held but nothing is running”A hold stays in place while a run is paused for your review. Approve or abandon the run and the hold settles.
If a hold persists with no run in flight, contact support with the change-set ID.
Nothing appears in the State tab
Section titled “Nothing appears in the State tab”The State tab populates once the architecture step produces a system design. Before that, there is nothing to show.
Getting help
Section titled “Getting help”If none of the above matches, include these when you ask for help:
- The change-set ID
- The service name
- The status reason shown in the change set panel
- Roughly when the problem occurred