TROUBLESHOOTING.md

Troubleshooting Guide

This guide helps you diagnose and fix common issues with ReviewRouter.

Table of Contents

• Installation Issues
• API Key Problems
• Provider Failures
• Performance Issues
• GitHub Integration
• Self-Hosted Deployment
• Advanced Debugging

---

Installation Issues

Problem: npm install fails with dependency errors

Symptoms:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

Solutions:

1. Update Node.js: Ensure you're running Node.js 20 or later

   node --version  # Should be v20.x or higher

2. Clear npm cache:

   npm cache clean --force
   rm -rf node_modules package-lock.json
   npm install

3. Use legacy peer deps:

   npm install --legacy-peer-deps

Problem: Tree-sitter installation fails

Symptoms:

Error: Cannot find module 'tree-sitter'
gyp ERR! build error

Solutions:

1. Install build tools:

   • macOS: xcode-select --install
   • Ubuntu/Debian: sudo apt-get install build-essential
   • Windows: Install Visual Studio Build Tools

2. Rebuild native modules:

   npm rebuild tree-sitter

3. Use pre-built binaries: Tree-sitter modules are marked as optionalDependencies, so the action will work without them (but with reduced functionality for some languages)

---

API Key Problems

Problem: OPENROUTER_API_KEY not found or invalid

Symptoms:

Error: OPENROUTER_API_KEY is required
Error: API key for openrouter is required

Solutions:

1. Verify key is set in GitHub Secrets:

   • Go to Repository Settings → Secrets and variables → Actions
   • Ensure OPENROUTER_API_KEY exists and is correct
   • Get a free key at openrouter.ai/keys

2. Check key format:

   • OpenRouter keys start with sk-or-v1-
   • Key should be ~64 characters long
   • No extra spaces or newlines

3. Test key locally:

   curl https://openrouter.ai/api/v1/models \
     -H "Authorization: Bearer $OPENROUTER_API_KEY"

Problem: Rate limiting errors

Symptoms:

Error: Rate limit exceeded
status: 'rate-limited'

Solutions:

1. Reduce parallel providers:

   PROVIDER_MAX_PARALLEL: '2'  # Default is 3

2. Enable incremental review:

   INCREMENTAL_ENABLED: 'true'  # Reduces API calls on updates

3. Use provider rotation:

   PROVIDER_LIMIT: '3'  # Use fewer providers per review

4. Reduce structured-output retry attempts:

   PROVIDER_RETRIES: '1'  # One total attempt, no JSON retry

---

Provider Failures

Problem: All providers fail

Symptoms:

Providers used: 3 (success 0, failed 3)
Review completed with 0 findings

Diagnosis: Check the "Raw provider outputs" section in the PR comment for specific error messages.

Common Causes:

1. API keys not set:

   • Verify all required API keys are in GitHub Secrets
   • Check .env.example for required keys

2. Network issues:

   • Providers may be temporarily unavailable
   • Check openrouter.ai/status

3. Invalid model names:

   • Verify model names in REVIEW_PROVIDERS
   • Check available models: openrouter.ai/docs#models

4. Budget exceeded:

   • Check BUDGET_MAX_USD setting
   • Review may be skipped if estimated cost exceeds budget

Problem: Specific provider times out

Symptoms:

Provider openrouter/model: timeout (30.0s)

Solutions:

1. Increase timeout:

   RUN_TIMEOUT_SECONDS: '900'  # Default is 600 (10 min)

2. Reduce diff size:

   DIFF_MAX_BYTES: '80000'  # Default is 120000

3. Exclude large files:

   EXCLUDE_PATTERNS: '**/*.lock,**/*.min.js,dist/**'

Problem: Free providers not working

Symptoms:

Error: Model requires credits
Error: No free credits available

Solutions:

1. Use confirmed free models:

   REVIEW_PROVIDERS: |
     openrouter/google/gemini-2.0-flash-exp:free,
     openrouter/mistralai/devstral-2512:free

2. Check model pricing:

   • Visit openrouter.ai/models
   • Look for models with "free" tag
   • Free models may have rate limits

---

Performance Issues

Problem: Review takes too long (>5 minutes)

Diagnosis: Check review duration in PR comment:

Duration: 300.0s • Cost: $0.1234 • Tokens: 50000

Solutions:

1. Enable incremental review (fastest):

   INCREMENTAL_ENABLED: 'true'  # 6x faster on PR updates

2. Reduce provider count:

   PROVIDER_LIMIT: '2'  # Use fewer providers
   PROVIDER_MAX_PARALLEL: '2'  # Reduce parallelism

3. Exclude unnecessary files:

   EXCLUDE_PATTERNS: '**/*.test.ts,**/*.spec.ts,dist/**,node_modules/**'

4. Disable expensive features:

   ENABLE_AST_ANALYSIS: 'false'  # Skip AST analysis
   GRAPH_ENABLED: 'false'  # Skip dependency graph

5. Use faster models:

   • Prefer "flash" or "turbo" variants
   • Example: gemini-2.0-flash-exp:free instead of slower models

Problem: High API costs

Symptoms:

Cost: $5.00 per review
Total monthly cost: $500+

Solutions:

1. Use free providers:

   REVIEW_PROVIDERS: |
     openrouter/google/gemini-2.0-flash-exp:free,
     openrouter/mistralai/devstral-2512:free

2. Enable incremental review:

   INCREMENTAL_ENABLED: 'true'  # 80% cost reduction on updates

3. Set budget limit:

   BUDGET_MAX_USD: '0.10'  # Skip reviews exceeding $0.10

4. Enable caching:

   ENABLE_CACHING: 'true'  # Cache findings for reuse

5. Review fewer files:

   MAX_CHANGED_FILES: '50'  # Skip reviews with >50 files

Problem: Action runs out of memory

Symptoms:

Error: JavaScript heap out of memory
FATAL ERROR: Reached heap limit

Solutions:

1. Reduce diff size:

   DIFF_MAX_BYTES: '50000'  # Smaller chunks

2. Exclude large files:

   EXCLUDE_PATTERNS: '**/*.lock,**/*.svg,**/*.min.js'

3. Use smaller runner: (Self-hosted only)

   runs-on: ubuntu-latest  # Has more memory than smaller runners

4. Disable graph features:

   GRAPH_ENABLED: 'false'  # Reduces memory usage

---

GitHub Integration

Problem: Comments not posting to PR

Symptoms:

• Action completes successfully
• No comments appear on PR
• No errors in logs

Solutions:

1. Check permissions:

   permissions:
     contents: read
     pull-requests: write  # Required for commenting

2. Verify token scope:

   • GITHUB_TOKEN should be ${{ secrets.GITHUB_TOKEN }}
   • Token needs pull_requests: write permission

3. Check PR state:

   • PR must be open (not closed or merged)
   • PR must not be a draft (unless configured to review drafts)

4. Check skip conditions:

   • Review labels: SKIP_LABELS setting
   • Draft PRs: SKIP_DRAFTS setting
   • Min/max files: MIN_CHANGED_LINES, MAX_CHANGED_FILES

Problem: Duplicate comments on every commit

Symptoms:

• New comment on every push
• Old comments remain

Solutions:

1. Enable incremental review:

   INCREMENTAL_ENABLED: 'true'  # Updates existing comment

2. Check workflow trigger:

   on:
     pull_request:
       types: [opened, synchronize]  # Not ready_for_review

3. Use concurrency control:

   concurrency:
     group: review-${{ github.event.pull_request.number }}
     cancel-in-progress: true

Problem: Fork PRs fail with secrets error

Symptoms:

⚠️  Skipping review for fork PR without OPENROUTER_API_KEY
Fork PRs cannot access repository secrets

Explanation: This is expected behavior for security. Fork PRs don't have access to repository secrets.

Solutions:

1. Manual trigger: Use workflow_dispatch to manually approve and run review
2. Use free providers without secrets: Not recommended for security reasons
3. Use GitHub App: Create a GitHub App with proper permissions (advanced)

---

Self-Hosted Deployment

Problem: Docker container won't start

Symptoms:

Error: Cannot find module './dist/index.js'
Container exits immediately

Solutions:

1. Build dist files:

   npm run build:prod

2. Verify dist directory:

   ls -la dist/
   # Should contain index.js and CLI files

3. Check Docker logs:

   docker logs mpr-review

4. Rebuild image:

   docker-compose build --no-cache
   docker-compose up -d

Problem: Webhook server returns 401 Unauthorized

Symptoms:

Webhook delivery failed: 401 Unauthorized
GitHub shows webhook delivery failure

Solutions:

1. Verify webhook secret:

   • Generate secure secret: openssl rand -hex 32
   • Set in .env: WEBHOOK_SECRET=your_generated_secret
   • Use same secret in GitHub webhook settings

2. Check signature header:

   • GitHub sends X-Hub-Signature-256 header
   • Secret must match exactly (case-sensitive)

3. Test locally:

   curl -X POST http://localhost:3000/health
   # Should return 200 OK

Problem: Rate limit errors in self-hosted mode

Symptoms:

Error: Rate limit exceeded for PR #123
Too many reviews per minute

Solutions:

1. Adjust rate limits:

   WEBHOOK_RATE_LIMIT_PER_MINUTE=20  # Default: 10
   WEBHOOK_RATE_LIMIT_PER_PR=10      # Default: 5

2. Check cleanup interval:

   • Rate limits reset automatically
   • Check logs for cleanup messages

3. Restart container:

   docker-compose restart mpr-webhook

---

Advanced Debugging

Enable Debug Logging

env:
  LOG_LEVEL: 'debug'  # debug, info, warn, error
  VERBOSE: 'true'

Check Action Logs

1. Go to Actions tab in GitHub
2. Click on failed workflow run
3. Expand "ReviewRouter" step
4. Look for error messages

Download Artifacts

Reports are saved as workflow artifacts:

1. Go to workflow run
2. Scroll to "Artifacts" section
3. Download review-router.json and review-router.sarif

Test Locally with CLI

# Clone repo
git clone <your-repo>
cd <your-repo>

# Install CLI
npm install -g review-router

# Review locally
mpr review

# Check cache
ls -la .mpr-cache/

# View analytics
mpr analytics summary

Debug Provider Issues

# Test specific provider
export REVIEW_PROVIDERS="openrouter/google/gemini-2.0-flash-exp:free"
export OPENROUTER_API_KEY="REPLACE_WITH_YOUR_KEY"
mpr review --dry-run

# Check provider health
# (Self-hosted only - health checks run automatically)

Common Error Codes

Error Code	Meaning	Solution
ENOENT	File not found	Check file paths, ensure fetch-depth: 0 in workflow
EACCES	Permission denied	Check file permissions, token scopes
ETIMEDOUT	Operation timed out	Increase timeout, check network
ERESOLVE	Dependency conflict	Clear cache, reinstall dependencies
ERR_MODULE_NOT_FOUND	Missing dependency	Run npm install, rebuild native modules

---

Getting Help

Check Documentation

• README.md - Quick start guide
• Self-Hosted Guide - Docker deployment
• Analytics Guide - Dashboard setup
• Plugin Development - Custom providers

Report Issues

If you've tried the solutions above and still have issues:

1. Check existing issues: GitHub Issues
2. Create new issue with:
   • Error message (full stack trace)
   • Configuration (sanitized - no API keys!)
   • Steps to reproduce
   • Environment (OS, Node version, runner type)
   • Relevant logs (from Actions or Docker)

Community Support

• Discussions: Use GitHub Discussions for questions
• Examples: Check __tests__ directory for usage examples
• Source Code: All code is open source - explore to understand behavior

---

Quick Fixes Checklist

• Node.js version ≥ 20
• All required API keys set in GitHub Secrets
• GITHUB_TOKEN has pull-requests: write permission
• Workflow has fetch-depth: 0 for incremental review
• Provider model names are correct
• No placeholder values in environment variables
• Budget limits not exceeded
• File patterns (include/exclude) are correct
• PR is not labeled with skip labels
• Webhook secret is secure (32+ characters)
• Docker container has built dist files
• Cache directory is writable
• Network allows outbound HTTPS

---

Last Updated: 2026-01-25 (v0.2.1)