Skip to main content
Match the stop you are looking at to an entry below, run its diagnostic command, then apply its fix.
Symptom: the run stops as Blocked before it creates a branch, and names an issue number the issue body mentions.PRFlow reads the issue body for a declared prerequisite. Show every phrase it looks for:
These are all the phrases that declare a blocking dependency, each followed by one or more issue numbers:One phrase can name several issues at once, as in blocked by #10 and #11.
follow-up to #123 reads like ordinary prose. People write it to record where the work came from, not to say the work is blocked, and PRFlow still treats it as a blocking dependency. If you meant a non-blocking reference rather than ordering, record it in Technical Context as Related work: #123, or reword the provenance, for example to this continues the work in #123.
Check whether the named prerequisite is actually still open:
Close or merge the prerequisite, or correct the issue text. Then start the run again. A phrase that points the other way, such as Blocks #123 or Required by #123, is read as an outbound relation and does not block the run.If the run says a dependency could not be resolved, that is not the same as closed. Fix GitHub authentication or repository access, then retry.
Symptom: the run stops as Blocked on a bug issue, and the workpad records a reflection beginning cannot reproduce: followed by the obstacle it hit.Reproduction is a hard gate for a bug issue. PRFlow will not plan a fix for a defect it has not seen happen, because a fix aimed at a guess is worse than no fix. It records the obstacle instead of inventing one.Read what it recorded:
The workpad comment holds the obstacle. Then give the run what it was missing by editing the issue’s Current Behavior section: the exact steps, the input that triggers the defect, the environment it happens on and the output you actually see against the output you expect. If the defect only happens in one environment, say which. If a fact genuinely cannot be established, write that down rather than leaving it out.Start the run again once the issue carries reproduction steps a second person could follow.
Symptom: nothing fails. The run finishes and reports Complete, and the workpad’s acceptance-criteria section reads _(none provided in issue body)_.Check whether the issue has the section at all:
With no criteria, the acceptance-criteria gate has nothing to check and passes trivially. A Complete on such a run means the run finished, not that the requested outcome was verified. Do not read it as evidence.
Write acceptance criteria into the issue before you run it. Each one is a testable statement about observable behavior, written as a markdown checkbox:
Then start the run again. Create an issue writes this section for you.
Symptom: the issue clearly has criteria, but the run behaves as though it has none, and its workpad carries a reflection about the issue’s accuracy that you did not cause.PRFlow reads a criterion only when it is a markdown checkbox list item: - [ ], - [x], * [ ] or * [x]. Bold paragraphs such as **AC1 — ...** and numbered lists such as 1. ... parse to zero items, exactly as an absent section would.Count the checkbox rows in the issue:
A count of 0 with a visible criteria section is this case. The run does not stop: it hand-extracts the criteria and records that it had to, which is the reflection you are reading. That reflection is about the issue’s shape, not about your code.Rewrite each criterion as a checkbox row, then start the run again so the machine-readable path is used.
Symptom: a local run stops as Blocked before it creates a feature branch, and the workpad lists the changed tracked files it found. With no workpad yet, the run reports the stop directly.Cloud runs. A cloud run does not stop for tracked changes. It inspects them, restores the ones setup or line-ending normalization produced, keeps any that are the run’s own uncommitted work, notes its decision in the workpad reflections and continues. If the reflections show setup rewriting tracked files on every run, make every setup.install command leave tracked files unchanged (for example, a lockfile your package manager rewrites), and match your repository’s line-ending and .gitattributes normalization.Local runs. The rest of this entry applies.PRFlow reaches this point still on your base branch, before any feature branch exists. Rather than sweep your uncommitted changes into a stray commit on the base branch, it stops and leaves your tree untouched.List what it found:
This is a terminal stop, and it moves nothing. Your changes are still in your working tree exactly as you left them.
Commit those changes on a branch of your own, or stash them:
Then start the run again. Untracked files do not trigger this stop; only tracked changes do. PRFlow never restores, commits or stashes files in a local tree.
Symptom: branch setup reports that the branch is checked out in another linked worktree (branch-live-in-other-worktree), naming that worktree’s path when it can be read. The run does not switch into that worktree. It continues on the branch it was started on when that branch belongs to this issue, and otherwise on a new branch cut from the base. If that recovery also stops, the run ends Blocked.A worktree in the middle of a rebase or bisect of the branch counts too. git worktree list shows that worktree as detached and the report names no path; finish or abort the rebase or bisect there to free the branch.List your worktrees and find the one holding the branch:
PRFlow shares the working tree it was started in and cannot move into another one, so the run never uses the branch the other worktree holds. A run that cut a new branch leaves the other worktree’s branch and its commits untouched.
To have the run use that branch, free it, then start the run again:
Finish and remove the other worktree, or move its work elsewhere. Use git worktree remove --force only when you are sure that worktree holds nothing you want.
Symptom: a resumed run stops as Blocked during branch setup, and the workpad reflection reads Branch setup stopped: landing stopped, no recovery: resume-precheck-checkout-did-not-land; <reason>.When a run resumes an open pull request, or a branch an earlier run pushed, it brings your local branch of the same name to the commits already pushed for it: it moves the branch only when no commit is lost, and keeps a branch that already contains those commits as it is. When it cannot do this safely, or cannot set the branch to track its pushed branch, it stops instead of continuing on the wrong commits, unless the cause is another worktree holding the branch (see the previous section). The <reason> names the cause:
  • local-branch-diverged: Your local branch holds commits that are on no branch fetched from origin, and the pushed branch holds commits your local branch lacks.
  • move-refused: The move was refused and your local branch is still where it was, typically because an uncommitted or untracked file in your working tree would be overwritten.
  • branch-fetch-failed: The branch could not be fetched from the remote.
  • fetched-tip-lacks-pr-head: The fetched branch does not contain the pull request’s head commit, for example after a force-push during setup.
  • checkout-refused, git-state-unestablished or upstream-not-set: Git refused the checkout; a repository state the check needs could not be established (for example, a git read failed, a shallow clone could not be deepened, or the base branch could not be fetched); or the branch could not be set to track its own remote branch.
Compare your local branch with the pushed one:
Lines marked < are commits only your local branch has; lines marked > are commits only the pushed branch has.
For local-branch-diverged, move-refused, branch-fetch-failed and fetched-tip-lacks-pr-head, your local branch is left where it was. With upstream-not-set, the branch was already checked out at the pushed commits, or ahead of them, and only its tracking setting failed.
Keep any local-only commits you want on a branch of your own, commit or stash conflicting files, then start the run again. A fetch failure or a force-push during setup usually clears on a plain re-run.
Symptom: the run stops before implementation and says it could not confirm that the existing commits on the feature branch belong to this issue’s earlier work.The run compares the feature branch against the base branch. List the commits that are on the branch but not on the base:
A refusal means those commits could not be shown to be the run’s own prior work. That usually happens when the branch was created from an unpushed local commit, so it carries unrelated history that every later step would treat as part of this change.Check the workpad’s branch and pull-request links, and confirm the remote branch still exists and points where you expect:
Do not clear the refusal by deleting the commits you do not recognize. Reconcile or publish that history on purpose first. The check is read-only and has moved nothing.
Symptom: a cloud run stops as Blocked rather than opening an empty pull request, and names workflow files.The built-in token cannot push a change to a workflow file. When every acceptance criterion needs that capability, the run has nothing it can ship.Check what the issue requires:
Either run the issue with a human credential, or configure the optional GitHub App with both Contents: write and Workflows: write. See Cloud Setup. If only part of the work is workflow-bound, PRFlow can defer that part and ship the rest.
Symptom: with CI verification enabled, the workpad or run log shows a first line of the form FAILED <request-id> run=<run-id> url=<url> conclusion=failure, then failed-job: and recap: lines, or recap-status: unestablished — <reason>.The helper already named the failed jobs and the suite identifiers. Do not treat a recap-status: line as a test identifier. Repair each recap: identifier and each failed-job: name, re-run the covering checks on the current tree, then request CI again.When the helper could not fetch jobs or logs, open the run URL from the FAILED line:
Expected result: the failed jobs and a Failure recap: block whose - bullets match the identifiers a current helper would print as recap: lines.The first FAILED line and exit status 7 are unchanged. PASSED, CANCELLED, SUPERSEDED and PENDING are also unchanged.
Symptom: wait exits 6 with a CANCELLED, SUPERSEDED or STALLED line. STALLED <request-id> run=<run-id> url=<url> queued-for=<n>s cancel=ok job=<job name> means a job waited for a runner for at least the --cancel-queued-after bound, so PRFlow cancelled the run. cancel=failed means the cancel call did not succeed: unless an earlier wait for that request printed CANCELLED, SUPERSEDED or STALLED … cancel=ok, a later request without --force-dispatch reuses the newest unsettled run it has correlated for that head, normally that same run, and the next wait --cancel-queued-after retries the cancel if a job is still queued past the bound. You can also cancel the run yourself from its URL.None of these carries a verdict on the change. Request CI again for the same head.
Symptom: the run stops and names a command it needed but was not allowed to run.Check the grant list for the implementation path:
The full fix, including why a grant added by the same pull request does not apply to that pull request’s own run, is in Command Problems.
Symptom: the workpad shows a status that is not Complete, and no finished pull request exists.Read the workpad and the run it came from:
The workpad holds the branch link, the pull-request link and the run’s own record of where it stopped. Fix the cause it names, then post the original implement comment again. The new run reuses the same workpad and adopts any checkpoint that was already pushed.A run interrupted before its first branch checkpoint may have no recoverable code. A cancelled run is terminal and is never resumed for you. See Cloud Recovery.