Investigate a review that went wrong

Use this guide when a review never started, failed, is taking too long, or finished but looks wrong. It walks you from the merge request (GitLab) or pull request (GitHub) to the review details in Gryndel, then to the fix, and tells you whether to replay the review or ask for a new one.

Who can do what: anyone with the Developer role on the GitLab project, or write access to the GitHub repository, can use the @gryndel commands. Anyone in the workspace can read the review details. Replaying a failed review, and changing settings, needs a workspace admin.

Start here: ask Gryndel

On the merge or pull request, comment:

@gryndel status

Gryndel replies in a few seconds, without using the model. Find its answer in this table (on GitHub, replies say "pull request" instead of "merge request"):

Gryndel replies	What it means	Go to
Gryndel has not reviewed this merge request yet.	No review exists for it.	It never started
A review of commit … is queued (waiting …).	It's waiting for a worker.	It's slow or stuck
Reviewing commit … running for …, attempt N. with a list of steps	It's running. The steps show what it's doing and how long each took.	It's slow or stuck
The review of commit … failed after N attempts: …	It gave up. The reason follows.	It failed
Reviewed commit … N findings posted, M withheld.	It finished.	It looks wrong
The latest review of commit … is skipped.	Gryndel saw the commit but didn't review it.	It never started
Automatic reviews are paused at the top	Someone commented @gryndel pause on this merge or pull request.	Comment @gryndel resume, then @gryndel review.
No reply at all	Gryndel isn't receiving this merge or pull request's comments, for example because the repository is paused or webhook deliveries are failing.	It never started
A reply saying Gryndel is turned off	An admin turned reviews off.	Pause reviews

Then open the review in Gryndel: go to Pull requests, search for the number (for example !42 for a GitLab merge request, #42 for a GitHub pull request), and click its title. The REVIEW DETAILS panel shows the status, attempts, runtime, model, progress, and any failure.

It never started

Work down this list. Each check takes a minute.

1. Is Gryndel healthy? Open System health. Your code host (GitLab or GitHub) and your model provider should both say ready.

2. Are reviews paused somewhere? On Pull requests, search for the merge or pull request. A skipped review means Gryndel saw the commit but reviews were paused. No review at all can also mean a pause:

   Paused where	How to tell	Fix
   This merge or pull request	@gryndel status says automatic reviews are paused; reviews are skipped	Comment @gryndel resume, then @gryndel review.
   The repository	Reviews says Disabled on Repositories; no reviews appear and commands get no reply	Set Review processing back to Enabled. Gryndel catches up on its own.
   Organization settings	Review processing is Paused in Organization settings; reviews are skipped	Set it back to Enabled, then comment @gryndel review on merge or pull requests that need it.
   The workspace	A banner on every page says reviews are turned off; Gryndel replies that it's off	Turn them on from Workspace.
   The target branch	The target branch's .gryndel.yaml sets enabled: false; reviews are skipped	Change the file, or target another branch.

   See Pause reviews for what each level does.

3. Is the repository turned on? On Repositories, its Reviews column must say Enabled and Webhook must not say needs attention. On GitHub, a repository missing from the list isn't in the GitHub App's installation: add it on GitHub, then click Refresh repositories.

4. Did the event reach Gryndel? Check the code host's record of webhook deliveries, as below.

GitLab

In GitLab, open the project's Settings → Webhooks, edit Gryndel's webhook, and look at Recent events for errors.

GitHub

GitHub sends events for every repository through the GitHub App's webhook. Whoever manages the App can open its settings on GitHub (Settings → Developer settings → GitHub Apps → the App's Edit), then the Advanced tab. Recent Deliveries lists each event with GitHub's result, and Redeliver sends one again.

For more causes, see A review never starts.

Once you've fixed the cause, comment @gryndel review to start a review of the latest commit.

It failed

1. Open the review in Gryndel. A red box says Review failed: with a failure code and an explanation. The progress list shows which step failed.

2. Check System health. A provider showing model unavailable, key rejected or unavailable explains most failures.

3. Fix the cause. Common ones:

   The failure mentions	Fix
   The model is no longer available, or the key was rejected	Choose another model, or save a valid key, in Model settings.
   The context window is unknown	Fill in Context window (tokens) for the provider in Model settings.
   The code doesn't fit	Lower Max files or Max context chars, or add Excluded paths, in the repository's Scope tab. Or use a model with a larger context window.
   A rate limit or a provider outage	Gryndel already retried. Wait, then try again.

4. Run the review again, by replay or by @gryndel review. See below.

Replay or review again?

	Replay failed run (in Gryndel)	@gryndel review (in GitLab or GitHub)
Who can	Workspace admins	Anyone with the Developer role in GitLab, or write access on GitHub
What it reviews	The same commit as the failed review	The latest commit of the merge or pull request
Which settings	The settings saved with the failed review	The settings in force now
When it's allowed	Only for a failed review that is still the newest for its merge or pull request, and only while the repository isn't paused	Any time reviews aren't paused for the repository or the organization. It does override a @gryndel pause on the merge or pull request.
Use it when	You fixed something outside the review, such as the model or a key	You changed the repository's settings or rules, or pushed new commits

To replay: open the failed review and click Replay failed run. You see Replay queued. Run status updates automatically. See Replay a failed review.

After an outage, filter Pull requests by status failed and replay each one that is still the newest for its merge or pull request.

It's slow or stuck

A review normally takes from under a minute to several minutes, depending on the size of the change, the review mode and the model. Compare with your usual times: Reports shows the median Review time and the time 90% of reviews finish within.

What you see	Meaning	Do this
queued for a long time	No worker has picked it up. Other reviews may be ahead of it.	Check how many reviews are running (the number next to Pull requests in the sidebar). If none are running, check System health.
running, one step taking very long, try 2 or more	The model is slow or the provider is retrying after errors.	Wait. Calls have a time limit and are retried. If it keeps failing, check the provider.
running with Attempts above 1	An earlier attempt failed and Gryndel is retrying. It tries up to three times by default.	Wait for the result.
No progress for a long time	The worker may have stopped.	Gryndel sends a review again by itself when it has made no progress for 15 minutes.

To stop a review that you no longer need, comment @gryndel cancel. It stops within a few seconds. Comment @gryndel review to start again later.

To make reviews faster: use Single pass or Verified instead of Agents mode, lower Max files, exclude generated code, or use a faster model. See Control costs; most of what saves money also saves time.

It looks wrong

The review finished, but it missed something, flagged something that isn't a problem, or said nothing at all.

1. Check what it covered. In the review details, the Change profile box shows how many files were reviewed and how many were left out. A grey +N in the Files column on Pull requests means N files were left out because of Max files or Max context chars. Left-out files also lower Review confidence.
2. Check what it held back. The Withheld tab lists findings Gryndel considered but didn't post, with the reason, such as verification rejected or severity policy. See Findings, Withheld and Verification.
3. Check what it was told. The details list the rules and guideline files the review used, and Applied repository policy shows its settings. Settings are fixed when a review is created, so a change you made afterwards isn't in it.
4. Check the model. The Model field shows which model did the review.

What you found	Fix
The missed problem was in a left-out file	Raise Max files or Max context chars, or exclude files that don't matter.
The finding was withheld as severity policy	Lower Min. severity to publish.
The finding was withheld as verification rejected and you think it was right	Read the verifier's reasoning on the Verification tab. If the verifier is often wrong, try a stronger model.
Your rule wasn't in the list	See Check that a rule works.
The review used old settings	Comment @gryndel review to review with the current ones.
A finding is simply wrong	Reply @gryndel ignore this in its thread. If it keeps happening, see Make Gryndel quieter and more accurate.

No findings doesn't prove the change is free of defects. Gryndel reviews the change with the context it can fit; it's a second pair of eyes, not a guarantee.