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 > Connections > 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-ai review on the PR.
  5. Do author or branch restrictions exclude it? Check pr_review.authors and pr_review.base_branches in .qodex.yaml or Settings > PR review. An empty list permits every author or base branch.
  6. Was the PR suppressed? A top-level @qodex-ai pause stops automatic reviews for new pushes. @qodex-ai ignore in the PR description does the same. A manual @qodex-ai review remains available.
  7. 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-ai 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, explain why in a reply to the finding. Qodex uses that feedback as repository-specific review context. Use @qodex-ai resolve in a top-level PR comment to close the PR’s open Qodex findings.

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

Three 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.
  1. Add @qodex-ai ignore to the PR description. This disables automatic reviews for that PR without changing repository configuration. A manual @qodex-ai review still works.
Each option leaves any resulting Check Run neutral; none 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.
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