Skip to main content

​
Troubleshooting PR review

Use this page when Qodex did not review a PR, a Check Run looks wrong, a finding seems misanchored, or you want to opt out. Most PR review issues come from one of four places: the repo is not linked, GitHub did not send a review-triggering event, .qodex.yaml changed the policy, or the preview deployment could not be checked.

​
Why didn’t Qodex review my PR?

Check these in order:
  1. Is the repo linked to your project? Open Settings > Integrations > GitHub > Repos in your project. If the repo is not in the list, link it via Connect a repo. Qodex skips PRs from repos no project has linked.
  2. Is the PR a draft? Draft PRs are skipped with a neutral Check Run and the reason “PR is a draft; Qodex will review on ready_for_review.” Mark the PR ready for review and the next push fires a review.
  3. Does .qodex.yaml opt out? When the repo has pr_review.enabled: false at the head SHA, the review is skipped with a neutral Check Run and the reason “Qodex review opt-out.” Set enabled: true (or delete the line) to re-enable.
  4. Did the action trigger a review? Only opened, synchronize, and reopened are actionable. A labeled or assigned event is acknowledged but does not run a review. To force a review on a non-triggering action, comment @qodex review on the PR.
  5. Did the GitHub App install lose access? If the App was uninstalled or the repo was removed from the install’s “Only select repositories” list, Qodex can no longer fetch the PR. Re-install the App or add the repo to the selected list.

​
Why is the Check Run stuck on in_progress?

The Check Run is posted at the start of the review and updated at the end. If it never updates to completed, the review didn’t finish cleanly. Two common causes.
  1. The LLM call timed out and the recovery write to GitHub also failed. If GitHub itself is degraded, even Qodex’s “this review failed” update can fail and the Check Run never updates.
  2. The Qodex server restarted mid-review. The in-flight review is lost and the Check Run is orphaned.
What to do:
  • Push a new commit or run @qodex review. A new review creates a new Check Run. The orphaned one will not block a merge because branch protection looks at the most recent Check Run with that name.
  • Wait for the head SHA to change. A synchronize event opens a new review on the new head SHA, and the orphaned one becomes irrelevant.

​
Why does Qodex post “Anchor uncertain” on a finding?

The anchor check fired. After a finding is pinned to a line, Qodex looks at the actual source text on that line. If it is clearly non-code, such as a comment, blank line, import, brace-only line, or markdown structural marker, the suggestion block is stripped and the Anchor uncertain badge is added. What to do:
  • Look nearby. The bug is usually within a few lines of the cited anchor. Misanchoring tends to happen when the relevant code sits below a comment block.
  • Treat as advisory. The description is still useful even when the line is wrong. If the description names a clear bug, the fix is real even when the suggestion was stripped.
  • If the description is also wrong, the finding is a false positive. Mark it in the Qodex Pull Requests view; slash-command resolution is on the roadmap.

​
How do I opt out of review for one PR?

Two options.
  1. Mark the PR a draft. Click “Convert to draft” in the GitHub PR header. Qodex skips drafts with a neutral Check Run. Reverting to “Ready for review” re-enables.
  2. Push a .qodex.yaml to the PR’s branch with pr_review.enabled: false. The config is fetched from the head SHA, so a per-PR opt-out is a per-PR file change. Useful when the PR is a generated diff (lockfile bump, version bump) that does not need review.
# PR-branch override
pr_review:
  enabled: false
Either choice lands the Check Run as neutral with the reason in the title. Neither blocks a merge.

​
How do I opt out of review for the whole repo?

Commit a .qodex.yaml at the repo root with pr_review.enabled: false. The file is fetched from the PR head SHA on every review, so committing to the default branch propagates to every new PR. 
# Repo-wide opt-out
pr_review:
  enabled: false
To re-enable, delete the line (or the file) and push. If you want to keep the reviewer but disable the Check Run gating, leave enabled: true and set block_pr_merge: false (the default). Findings still post; the Check Run is always neutral. If you want the full nuclear option, uninstall the Qodex GitHub App on the account at github.com/settings/installations. The webhook stops; the Check Run stops; no comment is ever posted. See Disconnect a GitHub account for the project-level partial-revoke.

​
Why is the walkthrough comment in two places?

The same PR linked from two Qodex projects gets two walkthroughs by design. See Multi-project routing. If this was not intentional, disconnect the install from the project you did not mean to link.

​
Why is the Check Run conclusion neutral when I have findings?

This usually means the repo is in advisory mode. The repo’s .qodex.yaml either has pr_review.block_pr_merge: false (the default) or no file at all, which also defaults to false. To gate merges, set block_pr_merge: true and add Qodex review to branch protection. See Check Run and merge gating. Even in gated mode, only verified findings at or above block_on_severity flip to failure. A walkthrough with five unverified findings still lands as success because nothing is blocking.

Limits and caveats

.qodex.yaml reference

How a review fires

Slash commands