Troubleshooting Guide

This guide centralizes common failure modes across the CLI, local reviewer, MCP server, VS Code extension, and SCM webhook integrations, along with deterministic remediation steps.

1. Run Diagnostics First (cjr doctor)

Before debugging manually, run the built-in diagnostic command:

cjr doctor

cjr doctor inspects:

• Node.js runtime version (>= 20 required)
• Git binary availability and repository root detection
• Active .codejackrabbit.yaml configuration validity
• Local or remote server connectivity (/health)
• Optional LLM provider credentials and external linter availability

2. CLI & Local Review Issues

No git repository detected or Empty Diff

• Cause: Running cjr review outside a Git worktree or on a clean working tree with no staged/unstaged changes.
• Fix:
• Run git status to verify you are inside a repository.
• To compare against a base branch instead of working tree changes, pass --base main: ```bash cjr review --local --base main ```

Configuration override warning in .codejackrabbit.yaml

• Cause: Invalid enum value (for example, an unknown profile or malformed pathInstructions entry).
• Fix: Run cjr config validate to print exact schema warnings and normalized defaults.

3. Server & Authentication Issues

HTTP 401 Unauthorized or HTTP 402 Payment Required

• Cause: Missing x-codejackrabbit-api-key header, expired surface lease, or exhausted monthly PR review quota (pr_reviews_monthly).
• Fix:
• Verify your API key with cjr auth status.
• Check current organization quota usage via GET /v1/usage.
• If a 3-phase metering reservation stalled after a network drop, release it via POST /v1/saas/metering/release.

HTTP 400 Invalid webhook signature

• Cause: Mismatch between the webhook secret configured in GitHub/GitLab/Bitbucket/Azure DevOps and the server's CJR_*_WEBHOOK_SECRET.
• Fix: Ensure the raw request body is not modified by an intermediate proxy and rotate the secret on both sides.

4. External Analyzers & LLM Fallback

External Tool Reported as not-installed

• Cause: tools.externalTools: true is enabled in .codejackrabbit.yaml, but the binary (eslint, ruff, semgrep, golangci-lint, trivy) is not on PATH.
• Fix: CodeJackRabbit automatically falls back to its built-in deterministic AST/heuristic analyzers. Install the binary on PATH if you want external tool findings merged into the review.

LLM Provider Timeout or Missing Key

• Cause: Provider API key is unset or the upstream model endpoint timed out.
• Fix: CodeJackRabbit never fails a review when an LLM is unreachable; deterministic static analysis, SAST, secret scanning, and blast-radius scoring always complete locally.