Reference

Troubleshooting

Find your symptom below. Each table lists the most common causes first, and rarer ones last.

A pull request wasn’t reviewed automatically

The HeyDeer Review check on the latest commit says why. Its title starts with Review skipped, or Review required when Fail the check when issues are found is on, followed by the reason. No check? See No HeyDeer Review check appears.

With Publish GitHub check off, HeyDeer comments on the pull request instead, once for each reason, when the pull request reaches Maximum automatic reviews per PR or HeyDeer can’t run the review. These comments are posted only while Post review comments on the pull request is on.

Likely cause	What to do
Review schedule is Manual only, the default for new workspaces.	Choose Once per PR or On every push. See Automatic reviews.
The pull request doesn’t match your automatic review filters, which skip drafts, forks and dependency updates by default.	Mark it ready, change the filters, or comment `@heydeer review`.
The review is queued while capacity is in use (Review queued).	Wait.
Once per PR already has a successful review, or the pull request reached Maximum automatic reviews per PR.	Comment `@heydeer review`.
The workspace ran out of credits or reached its usage limit.	Wait for the next Free refresh, choose a paid plan or add credits, or raise the limit in Usage & billing → Overview → Spending controls, then request a new review. See Auto-reload and usage limits.
Automatic reviews are paused on this pull request.	Comment `@heydeer resume`.
The commit already has a review; relabeling or reopening doesn’t repeat it.	Push a new commit, or comment `@heydeer review`.
HeyDeer’s GitHub access doesn’t include the repository.	Check Workspace settings → GitHub connection. See GitHub App and permissions.
The repository is linked to Free credits in another workspace.	Choose a plan, then request a review.

The check failed or the review didn’t finish

Check title	Cause	What to do
Review found issues that need attention	The review reported findings or open earlier concerns with Fail the check when issues are found on.	Fix them and push. To decline one, someone with write access explains the decision or resolves the conversation, then comments `@heydeer review`.
Review canceled	Someone canceled the review, its pull request closed, or a newer push replaced it.	Request another review.
Review incomplete	A repository check didn’t run or an earlier concern wasn’t rechecked.	Request another review.
Review failed / Review timed out	The review didn’t complete. HeyDeer returns its credits, unless it called a connector.	Request another review.
Review could not run	GitHub or HeyDeer was unavailable.	Request the review again.
No reviewable files	Every changed file is out of scope, such as generated files.	Nothing to do.

All conclusions are listed in The HeyDeer Review check.

HeyDeer didn’t approve a pull request

When automatic approval is on, the review’s page in HeyDeer shows Not automatically approved with the reason. Every requirement is in Automatic approval.

Likely cause	What to do
Automatic approval is off, the default.	Turn on Automatic approval under Publish results in Review rules. See Turn on automatic approval.
Findings or earlier concerns remain.	Fix them and push, or decline them. To approve with only Low findings left, set Remaining issues to Allow Low issues.
PRs HeyDeer may approve: the pull request’s risk level is above your setting.	A person approves it on GitHub; the review states the level and why. To let HeyDeer approve such pull requests, choose a higher level under PRs HeyDeer may approve.
Needs clarification: HeyDeer has a question the code can’t answer.	Answer it in a new PR comment that includes `@heydeer review`. See Add missing context.
The review has review notes, for example a repository check didn’t run.	Fix what the note describes, then request another review.
Earlier concerns couldn’t be fully checked.	Request another review.
Post review comments on the pull request is off.	Turn it on. HeyDeer approves by posting a review.

When the pull request changed, is a draft, or HeyDeer opened it

Likely cause	What to do
New commits were pushed, or the base branch moved, after the review.	Request or wait for a review of the latest commit.
The pull request is a draft.	Mark it ready for review, then request a review.
HeyDeer opened the pull request, for example a fix PR.	A person needs to approve it.

No HeyDeer Review check appears

Likely cause	What to do
The repository is on Manual only and has never been reviewed.	Request a review. Later revisions then get a check.
Publish GitHub check is off for the repository.	Turn it on. See Publishing results.
HeyDeer lacks the Checks read & write permission on GitHub, or its GitHub access doesn’t include the repository.	A GitHub owner selects Review permission request or Add repositories in Workspace settings → GitHub connection.
The pull request is closed.	Reopen it.

A command got no reply or an error

Likely cause	What to do
No reply or 👀 reaction: the command is in code, a blockquote or an HTML comment, was added in an edit, or was posted by a bot.	Post the command as plain text anywhere in a new PR comment or inline review comment, from a personal account.
You lack write access, or aren’t listed under Manual review access.	Ask an admin, or someone who has access.
Not enough credits, or the usage limit is reached.	Choose a plan or add credits, or raise the limit, then post the command again.
Too many requests, or the review queue is full.	Wait, then post the command again.
No 👀 reaction: HeyDeer may lack Issues read & write for PR conversation comments or Pull requests read & write for inline review comments.	A GitHub owner selects Review permission request in Workspace settings → GitHub connection and approves it on GitHub.
`pause` or `resume` on a closed pull request.	These work only on open pull requests.
GitHub was unavailable.	Post the command again in a new comment.

Every command is listed in PR comment commands.

A convention or check seems ignored

Likely cause	What to do
The check’s patterns match no changed file, its frontmatter has no `files`, or the file isn’t a .md file directly in `.agents/checks/`.	Fix the frontmatter or patterns, or move the file. See Repository checks.
The finding was outside your feedback scope.	Try Balanced or Detailed. See Feedback scope.
The AGENTS.md convention is in a directory that doesn’t cover the changed files.	Move it. See AGENTS.md.
The REVIEW.md is in a directory that doesn’t cover the changed files.	Move it. See REVIEW.md.
Instructions were saved after the review was requested, or repository instructions override them.	Request another review, or resolve the conflict. See Review instructions.
The check asks for something HeyDeer can’t verify by reading the code.	Rewrite it as a condition HeyDeer can verify by reading the code. See Write an effective check.
The file is marked linguist-generated in `.gitattributes`, or it is a lock file the base branch already has.	Remove the attribute, or mark a lock file `-linguist-generated`. See What HeyDeer reads.

The review has review notes

HeyDeer lists what limited a review under Review notes. Each review note turns off automatic approval for that review. See Review notes.

Review note	What to do
Some findings were omitted	Fix or decline the findings shown, then request another review.
Too many repository checks matched	Narrow the checks’ file patterns, then request another review. See Repository checks.
Some repository checks are invalid	Fix the checks the review note names, then request another review. See Repository checks.
Some repository checks could not be completed	Request another review.
Some findings or earlier concerns couldn’t be fully assessed	Request another review.

Signing in and GitHub access

Likely cause	What to do
Your GitHub sign-in expired, and HeyDeer shows Sign in with GitHub.	Select it to sign in again and return to the same page.
You’re signed in with a GitHub account that can’t see the review or organization.	Select Continue with GitHub or Sign in to GitHub again, then choose the right account on GitHub.
An organization or repository is missing when you connect.	Under Don’t see your account?, sign in through SSO on GitHub if needed, then select Sign in to GitHub again. See GitHub App and permissions.

Billing problems

Likely cause	What to do
The card was declined, or your bank asked to verify the payment.	For a subscription payment, select Complete payment in Usage & billing → Overview. For other purchases, use another card.
Add credits says you need a plan.	Choose a plan first, or select Complete payment if Overview shows it. See Plans and add-on credits.
Auto-reload is Off, with a reason below it.	Fix the cause, then turn it on again. See When auto-reload fails.
Renewal payment pending.	Your plan stays active meanwhile. If the payment failed or needs your bank’s confirmation, HeyDeer emails the workspace; select Complete payment.
A payment is still processing, or Add credits asks you to check an earlier purchase.	Select Check purchase until it shows the result. Don’t start another purchase.
Add credits or auto-reload says a purchase limit was reached.	Try again later, or contact HeyDeer.
Payments and new paid reviews are paused.	HeyDeer is resolving a billing issue with the workspace. Contact HeyDeer.

Connector problems

Only admins marked GitHub owner or Account owner can manage connectors. See Connectors.

Likely cause	What to do
HeyDeer can’t load the tools.	Check that the endpoint is the server’s public Streamable HTTP address and that the headers hold valid credentials.
Reviews and tasks don’t use connectors without an active paid plan.	Connectors are included in paid plans. Choose a plan; saved connectors then apply to new reviews and tasks.
The review or task started before you saved the connector.	Settings apply to reviews and tasks started after you save. Start a new one.
The review or task page lists a connector as unavailable.	The repository is public, or the change comes from a fork or someone without write access. Choose Public repositories and forks too only for public data.
A review used none of a connector’s tools.	Reviews call only allowed read-only tools. Allow one under Read-only tools, or ask the server’s provider to mark its read-only tools.
A review failed after calling a connector.	Its credits aren’t returned. Request a new review.