> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting PR review

> Fix common PR review issues, including skipped reviews, plan limits, neutral checks, uncertain anchors, and opt-outs.

# 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](https://qodex.ai/docs/pr-review-connect-repo.md). 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 to start a review.
3. **Are automatic reviews off?** When **Automatic reviews** is off in the repo's review settings, or the repo has `pr_review.enabled: false` in `.qodex.yaml` at the head SHA, opening or pushing to a PR is skipped with a `neutral` Check Run titled "Review on request". Comment `@qodex-ai review` or click **Run review** to get a review, or turn automatic reviews back on.
4. **Did the action trigger a review?** Only `opened`, `synchronize`, `reopened`, `ready_for_review`, and a base-branch change start a review automatically. A `labeled` or `assigned` event is acknowledged but does not run a review. To force a review, comment `@qodex-ai review` on the PR.
5. **Did the project reach a plan limit?** A "Qodex review skipped: plan limit" Check Run means the project used the pull requests its plan includes this month, or this PR used every review its plan includes. See [PR-review plan limits](https://qodex.ai/docs/pr-review-limits-caveats.md#pr-review-plan-limits).
6. **Do author or branch restrictions exclude it?** Check `pr_review.authors` and `pr_review.base_branches` in `.qodex.yaml` or the repo's review settings. An empty list permits every author or base branch.
7. **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.
8. **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?

Four options.

1. **Mark the PR a draft.** Click "Convert to draft" in the GitHub PR header. Qodex skips drafts with a `neutral` Check Run. Marking it "Ready for review" starts a review.
2. **Comment `@qodex-ai pause` on the PR.** This stops automatic reviews for new pushes. `@qodex-ai resume` turns them back on.
3. **Push a `.qodex.yaml` to the PR's branch with `pr_review.enabled: false`.** The config is fetched from the head SHA, so this turns off automatic reviews for that PR only. Useful when the PR is a generated diff (lockfile bump, version bump) that does not need review.

```yaml theme={null}
# PR-branch override
pr_review:
  enabled: false
```

4. **Add `@qodex-ai ignore` to the PR description.** This disables automatic reviews for that PR without changing repository configuration.

In each case, a manual `@qodex-ai review` still runs a review. Each option leaves any resulting Check Run `neutral`; none blocks a merge.

## How do I stop automatic reviews for the whole repo?

Turn off **Automatic reviews** in the repo's review settings (the **Settings** tab on **Code > PR review**, or **Settings > PR review**). Or 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.

```yaml theme={null}
# Review on request only
pr_review:
  enabled: false
```

With automatic reviews off, the repo is review-on-request: `@qodex-ai review` and the **Run review** button still start a review, and each one counts against the plan. To turn automatic reviews back on, switch the setting on, or delete the line (or the file) and push.

To stop reviews on a repository entirely, unlink it from the project. See [Unlink a repository](https://qodex.ai/docs/integrations-github.md#unlink-a-repository).

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](https://qodex.ai/docs/pr-review-disconnect.md) 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](https://qodex.ai/docs/pr-review-multi-project-routing.md). 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](https://qodex.ai/docs/pr-review-check-run.md).

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.

## Related

> [card] [Limits and caveats](https://qodex.ai/docs/pr-review-limits-caveats.md)

> [card] [.qodex.yaml reference](https://qodex.ai/docs/qodex-yaml-reference.md)

> [card] [How a review fires](https://qodex.ai/docs/pr-review-how-it-fires.md)

> [card] [Slash commands](https://qodex.ai/docs/pr-review-slash-commands.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.