Troubleshooting
What to check when a labelled pull request does not move.
Read the sticky comment and the autofeat/review check before you change labels. See Reading the state comment and Labels.
| Symptom | Cause | Fix |
|---|---|---|
| Nothing happened after you added a label | The receiver ignored the webhook, or the router refused before a check. | Use the rows below. |
Check autofeat/review (or another autofeat/* check) completed as failure and the summary names policy | Policy on the default branch refused the action. | Change .autofeat/config.yml on the default branch. The pull request branch does not change policy. |
Sticky state is budget_exceeded | A ceiling in budget was crossed. The state is terminal. | Raise budget.* on the default branch, or ask an operator to reconcile. Removing a label does not resume the run. |
Sticky state is waiting_for_author | The last turn finished and is waiting for a new head. This state is not terminal. | Push a new commit. Re-adding autofeat:go on the same head does not start another turn, unless the last run was an infra failure. |
Sticky says the payload is unreadable, or refs/heads/autofeat-state/pr-<N> is missing | The journal ref is missing or its commit message was cut. | Operator only: autofeat reconcile prepare, review the file, then autofeat reconcile apply. A 404 on that ref also means the pull request never ran. |
| Two autofeat paths fight over one repository | .github/workflows/autofeat.yml is present and the hosted App is installed. | Keep one path. For the hosted App, delete that workflow and the Actions secrets AUTOFEAT_APP_ID and AUTOFEAT_APP_PRIVATE_KEY. See Actions path. |
Nothing happened after labelling
The hosted receiver answers 200 and does not start a run when any of these are true. The reason is only in the receiver log:
| Log reason | Meaning |
|---|---|
ignored_installation | The installation id is not allowlisted. |
ignored_repository | repository.full_name is not in the repository allowlist. Stored names are lower case. |
ignored_paused | pause_all is set on the deployment. |
The portal shows waiting for operator approval until both the installation and the repository are allowlisted. See Portal and Admin API.
Also check the pull request itself:
autofeat:gois absent. The router refuses with no new turn. Add the label.autofeat:stoporautofeat:pauseis present. Stop and pause win over go. Remove the blocking label, then push a new head or re-add go. Removing the label alone does not resume. See Labels..autofeat/config.ymlon the default branch is missing or invalid. Extra keys are errors.doctorFAIL on theconfigrow names the error. Fix the file on the default branch.- The event is not one autofeat routes:
opened,labeled,synchronize,reopened,edited(base change), or an issue comment on the pull request.
A fork is not a silent skip for review. With security.allow_forks: false (the default), review can start. plan, implement, and test are refused in the open and the check completes as failure. The summary says the fork was refused. Set allow_forks: true on the default branch only if you intend that.
Policy refusal
A failure conclusion with a policy reason means the default-branch snapshot refused the action or the method. policy_sha on the sticky comment is that commit. Edit the file on the default branch, merge it, and open a new turn. Pushing the config file on the pull request does not change the run.
native review and the flow method are refused by policy. Use delegate for review. See Agents and models.
budget_exceeded
The run stopped because budget.usd, budget.tokens, budget.minutes, or budget.turns was crossed. Terminal states do not resume when you remove a label.
- Raise the ceiling in
.autofeat/config.ymlon the default branch. - Or ask the operator to correct the ledger with
autofeat reconcile.
budget.alert_usd is only a warning banner. It does not set budget_exceeded. See Budgets and billing.
waiting_for_author
The agent stopped and asked for a human change. The check conclusion is neutral.
Push a commit (a synchronize event) so head_sha changes. Reopening the pull request also routes. Re-adding autofeat:go while the head SHA is unchanged does not start a turn when the state is waiting_for_author, failed, or approved, unless that last run was an infra failure.
failed is not terminal. The same new-head rule applies.
Journal unreadable or ref missing
The durable copy is the git ref refs/heads/autofeat-state/pr-<N>. The commit message is the sticky body. Reading it:
gh api "/repos/OWNER/REPO/git/ref/heads/autofeat-state/pr-N"
gh api "/repos/OWNER/REPO/git/commits/SHA"Replace SHA with object.sha from the first response. A 404 on the ref means there is no journal yet, or the ref was deleted.
When the marker <!-- autofeat:state --> is present but the JSON fence cannot be read, every normal reader refuses. Only autofeat reconcile may adopt the sticky comment when the ref is missing, and only an operator should run it. Repo owners do not have that credential on the hosted deployment. See CLI.
Actions path conflict
One repository, one path. The hosted App and autofeat init both try to own the pull request. If both are installed, delete .github/workflows/autofeat.yml and the Actions secrets AUTOFEAT_APP_ID and AUTOFEAT_APP_PRIVATE_KEY, then use the App. doctor on a hosted repo still looks for that workflow file. A FAIL on the workflow row is the Actions-path check. It does not mean the hosted App is down. See Actions path.