Troubleshooting

1. Review did not post on a PR

Symptom: you opened or pushed to a PR, waited 1-2 minutes, and no TriRev review comment appeared.

Most likely cause: the repository is not actually included in the install scope.

Fix:

1. Go to your GitHub Settings → Applications → Installed GitHub Apps.
2. Click Configure next to TriRev.
3. Under Repository access, check that the repository in question is either covered by All repositories or explicitly listed under Only select repositories.
4. If it is not, add it and save. The next push to the PR will trigger a review.

Other possible causes (check in this order):

• Your monthly Free quota (30 reviews) is exhausted. See issue #4 below.
• The PR has a trirev:skip label. Remove it.
• The PR only changes binary files, lockfiles, node_modules, or paths matching your .trirev.yml ignore_paths. There is nothing to review.
• The PR is a draft and your config waits for "ready for review". Mark it ready or change review_drafts: true in .trirev.yml.

If none of the above apply: open a new push or close + reopen the PR to force a fresh webhook delivery. If still silent, see issue #2 below.

2. Welcome issue did not appear

Symptom: you finished the install but no TriRev is installed - getting started checklist issue showed up in any repository.

Most likely cause: org-level install with zero accessible repositories at install time.

Fix:

1. Verify the install actually targeted at least one repo: GitHub Settings → Applications → TriRev → Configure → check "Repository access".
2. If no repos are selected, add at least one. The welcome issue is created on the first repository alphabetically in the install scope.
3. Re-install or re-select repositories: GitHub generates a new installation.created event and TriRev creates the welcome issue on the new scope.

Other possible causes:

• The welcome issue already exists from a prior install. TriRev is idempotent on the welcome issue title; it will add a comment on the existing one rather than create a duplicate. Search your issues for TriRev is installed.
• A webhook delivery temporarily failed. Wait 2-3 minutes (GitHub retries), then re-check.

The welcome issue is the only thing TriRev creates on install. It is safe to close.

3. Webhook returns 4xx or 5xx in GitHub's "Recent deliveries" panel

Symptom: in your GitHub App settings under Advanced → Recent deliveries, you see TriRev webhook events with red status codes (4xx or 5xx).

Cause: GitHub delivered the event but TriRev's webhook endpoint refused or errored.

Fix:

You can manually re-deliver any failed event from that same Recent Deliveries panel by clicking Redeliver. This is safe; TriRev deduplicates events by delivery_id.

4. Free quota cap hit (30 reviews this month)

Symptom: TriRev posts a comment on your PR that reads:

TriRev free quota reached for {Month YYYY} (30/30). Reviews resume on {next_reset_date}. Upgrade to Pro for instant unlock.

The values in braces are filled in dynamically by TriRev. A real comment reads, for example: "TriRev free quota reached for April 2026 (30/30). Reviews resume on 2026-05-01."

This is not an error. You used 30 PR reviews this calendar month on the Free plan, which is the documented cap.

Fix - choose one:

• Wait for monthly reset. The cap resets at 00:00 UTC on the 1st of next month. No action needed; reviews will resume automatically.
• Upgrade to Pro for $20/dev/month. Open the Pro plan page on Marketplace. After purchase, the next push to any PR triggers a review immediately - no wait.

The cap is per installation per UTC calendar month, counted as unique (repository, PR number) combinations. Re-pushing to the same PR within a month counts ONCE. Force-pushes do not multiply the count.

A usage dashboard is on the roadmap. Until it ships, the cap-hit comment on your PR is the authoritative signal.

5. PR is too large

Symptom: TriRev posts a comment that the PR exceeds size limits and skips the review.

Cause: very large diffs (thousands of lines, many files) blow past TriRev's per-PR token budget. The default upper bound covers the vast majority of real-world PRs.

Fix:

• Split the PR into smaller, logically scoped PRs. Each one will be reviewed independently.
• If a single large PR is unavoidable (e.g. a generated migration), exclude the relevant paths in .trirev.yml:

  ignore_paths:
    - "**/migrations/**"
    - "**/*.generated.*"

• There is no "force review anyway" override at v1. The cap is a cost protection on our side; a controlled override is on the roadmap once per-PR cost telemetry is shipped.

If you hit this on a PR you genuinely cannot split, contact us via the Contact link in the FAQ. We track these to inform the cap-tuning roadmap.

6. .trirev.yml parse error

Symptom: TriRev posts a comment that your config file failed to parse, and the review uses defaults.

Cause: the YAML in .trirev.yml has a syntax error or contains an unknown key.

Fix:

1. Validate your YAML locally: yq '.' .trirev.yml or paste it into yamllint.com.
2. Check the error message TriRev posted on your PR. It includes the line number and the offending key or value.
3. Compare against the Configuration reference. Common mistakes:
   • Indenting with tabs instead of spaces.
   • Setting severity_threshold to a value not in {low, medium, high, critical}.
   • Misspelling an agent name under agents: (must be correctness, security, or style).
4. Push the fix. The next PR opened or updated picks up the corrected config.

TriRev never silently drops your config. If parsing fails, you always get a comment AND the review still runs with safe defaults.

7. Private repository did not get a review even though it is in scope

Symptom: TriRev reviews PRs on your public repos but ignores PRs on private repos in the same install.

Most likely cause: the install was originally scoped to "Only select repositories" and the private repo was added to the org AFTER the install. New repositories are NOT auto-included on a "select repositories" install.

Fix:

1. GitHub Settings → Applications → TriRev → Configure.
2. Under Repository access, scroll to your private repo and enable it. Save.
3. Open a new push to the PR. The review fires within ~30 seconds.

To avoid this in the future, switch the install to All repositories under the same configure screen. New repos are then auto-covered.

The Free plan, Pro plan, and Team plan all support private repos identically; there is no plan-related reason for a private-repo skip.

8. False positive in a review

Symptom: TriRev flagged something on your PR that is not actually a bug.

This is expected sometimes. TriRev uses LLM-based analysis, which trades off "always right" for "covers the cases AST tools miss". Some false positives are part of the product.

Fix - by intensity:

• One-off: ignore the comment. There is no "thumbs down" affordance at v1; we read every PR for false-positive patterns and tune the agents weekly.
• Pattern across PRs: raise the confidence threshold in .trirev.yml:

  confidence_threshold: 0.85

  Default is 0.7. Higher values reduce both false positives AND legitimate findings, so move in 0.05 increments.
• Always wrong on a specific category: raise the severity threshold or disable the agent that produced it:

  severity_threshold: high
  agents:
    style: false

If a single finding type is consistently wrong on your codebase (e.g. a custom convention that TriRev keeps fighting), tell us via the Contact link. Pattern reports drive the agent prompts in the next release.

9. Multiple TriRev review comments on the same PR

Symptom: TriRev posted two or more review comments on a single PR.

Possible causes:

1. The PR was closed and reopened. Each reopen triggers a new review run.
2. A webhook was redelivered (you or GitHub manually reran a delivery). TriRev deduplicates within a short window but a deliberate replay outside that window will post a fresh review.
3. Two TriRev installs on the same org are both reading the repo. Verify in GitHub Settings → Applications that you only have one TriRev install per account or organization.
4. A bot account opened the PR. TriRev reviews PRs from bot authors normally; if you have multiple AI review tools installed, each posts its own review.

Fix (matching the cause numbers above):

1. Nothing to do. Each review counts ONCE toward your monthly cap (we dedupe by unique (install, repo, pr), not by review-comment count).
2. Same as cause 1: nothing to do.
3. Uninstall the duplicate TriRev install via GitHub Settings → Applications → TriRev → Configure → Uninstall at the bottom of the page. Pick the install you want to keep.
4. Configure the other tools to skip TriRev's PRs, or vice versa. TriRev does not coordinate with third-party reviewers.

10. Account, billing, or cancellation question

For anything billing-related (upgrade, downgrade, cancel, refund, plan change):

• Upgrade Free → Pro: open the Pro plan on Marketplace. Effective immediately on next PR.
• Cancel a paid plan: GitHub Settings → Billing & plans → cancel TriRev. You keep Pro features until the end of the current billing period, then automatically revert to Free (30 PRs/month).
• Refunds: handled by GitHub Marketplace, not by TriRev. Open a request via your Marketplace billing page.
• Change plan mid-month: same flow as cancel; GitHub handles proration per their Marketplace policy. We see only the resulting plan-change webhook.

For anything we have not covered here, see the FAQ or the Contact link at the bottom.

Still stuck?