Troubleshooting

"Review artifacts are stale"

Caliper checks whether generated artifacts (.caliper/checks.js, .caliper/conventions.yaml, .caliper/doc-index.json) are older than your convention sources. Run:

npx caliper refresh

Or skip the check with --skip-refresh:

npx caliper 42 --skip-refresh

Missing ANTHROPIC_API_KEY

Caliper validates the API key before any AI calls. Set it in your environment:

export ANTHROPIC_API_KEY=sk-ant-...

No changed files

If the PR has no changed files (or all files are excluded by your excludeFiles patterns), Caliper exits with "No changed files found. Nothing to review."

Check your excludeFiles config if files you expect to review are being excluded.

Rate limiting on large PRs

Large PRs with many files create multiple concurrent AI calls. If you hit Anthropic rate limits:

1. The review phase uses concurrency control, but limits depend on your API tier
2. Consider splitting large PRs into smaller ones
3. Use --resume to continue after a rate limit error clears

Resuming after failures

State is saved after each phase completes. If a phase fails mid-execution:

npx caliper 42 --resume

The review resumes from the last successfully completed phase. In-progress work from the failed phase is re-run.

State directory location

Review state is persisted to /tmp/caliper/<pr-number>/state.json. Trace data is at /tmp/caliper/<pr-number>/trace.json and /tmp/caliper/<pr-number>/trace.html.

On most systems, /tmp/ is cleared on reboot. If you need to preserve state across reboots, copy the state directory before shutting down.

Common errors

Error	Fix
GitHub CLI (gh) not found	Install from cli.github.com
GitHub CLI not authenticated	Run gh auth login
Failed to fetch PR #N metadata	Check the PR number and that gh has access to this repo
ANTHROPIC_API_KEY is not set	Get a key at console.anthropic.com and export it
Invalid API key	Check that ANTHROPIC_API_KEY is correct and not expired
Anthropic rate limit hit	Wait a minute, then retry with --resume
Anthropic API overloaded	Wait a few minutes, then retry with --resume
GitHub rate limit hit	Wait a few minutes, then retry with --resume
gh CLI timed out	Check your network connection and retry with --resume
Diff exceeds 50 MB buffer limit	The PR is too large — split it into smaller PRs
Error: not a git repository	Run npx caliper from inside a git repo
Cost warning exceeds threshold	Adjust costWarningThreshold in .caliper/config.yaml (default: $2)

"caliper: command not found"

The caliper binary is not on your PATH. This typically happens when npm's global bin directory is not in your shell's PATH.

Find where npm installed it:

npm bin -g

Add it to your PATH (adjust for your shell):

# ~/.zshrc or ~/.bashrc
export PATH="$(npm bin -g):$PATH"

Reload your shell (source ~/.zshrc) and verify:

caliper --version

If you prefer not to modify your PATH, use npx instead:

npx @caliperai/caliper doctor
npx @caliperai/caliper check

Credit balance / wrong API key errors

If you see "Credit balance is too low" or "Invalid API key", the ANTHROPIC_API_KEY in your environment is wrong, expired, or belongs to a workspace with no credits.

Verify which key is loaded:

echo $ANTHROPIC_API_KEY

Common causes:

• Multiple keys in different shell profiles (.zshrc vs .bashrc vs .env) — one overrides the other
• Key belongs to a workspace that has exhausted its credit balance
• Key was rotated in the Anthropic console but the old value is still exported

Fix: Log in to console.anthropic.com, confirm your workspace has available credits, copy the active key, and re-export it:

export ANTHROPIC_API_KEY=sk-ant-...

Add it to your shell profile so it persists across sessions.

GitHub CLI not found or not authenticated

Caliper uses the gh CLI to fetch PR metadata, diffs, and post review comments. If gh is missing or not logged in, PR review commands will fail.

"GitHub CLI (gh) not found" — install it:

# macOS
brew install gh

# Other platforms: https://cli.github.com

"GitHub CLI not authenticated" — log in:

gh auth login

Follow the prompts to authenticate via browser or token. Verify with:

gh auth status

If you have access to multiple GitHub accounts or organizations, make sure gh is authenticated to the one that owns the repo you're reviewing.

Large PR timeouts

Very large PRs (many files, large diffs) can hit API timeouts or context limits. Symptoms include slow reviews, Anthropic API errors, or the "Diff exceeds 50 MB buffer limit" error.

Exclude noisy files by adding patterns to .caliper/config.yaml:

excludeFiles:
  - "package-lock\\.json"
  - ".*\\.generated\\.ts"
  - "dist/.*"
  - ".*\\.snap"

Force fast path to skip synthesis, lenses, and consolidation:

npx caliper 142 --fast

Resume after a timeout instead of starting over:

npx caliper 142 --resume

If the PR is genuinely too large, consider splitting it into smaller PRs. Caliper works best on focused, reviewable PRs.

Convention checks find nothing

If npx caliper check reports zero violations when you expect results, the check framework may not have anything to work with.

No CLAUDE.md in the repo — convention checks are compiled from your CLAUDE.md files. If none exist, there are no project-specific checks to run. Create a CLAUDE.md at your repo root with your coding conventions, then compile:

npx caliper refresh

No .caliper/checks.js — even with a CLAUDE.md, you need to compile it into executable checks:

npx caliper refresh

This generates .caliper/checks.js from your CLAUDE.md directives.

Preset not detected — Caliper auto-detects your language to load built-in check packs. If detection fails, checks specific to your language won't run. Verify detection with:

npx caliper config

Look for the preset field in the output. If it's wrong or missing, set it explicitly in .caliper/config.yaml:

preset: typescript # or python, go, ruby, rust, java

caliper doctor

When something is not working, npx caliper doctor runs a full health check and prints a pass/fail checklist:

npx caliper doctor

It verifies:

• Node.js >= 20
• GitHub CLI (gh) installed
• GitHub CLI authenticated
• .caliper/ directory exists
• .caliper/config.yaml is valid
• ANTHROPIC_API_KEY is set
• Anthropic API is reachable

Items marked as failed tell you exactly what to fix. Critical failures (Node.js version) cause a non-zero exit code.

Debug mode

When reporting an issue or investigating unexpected behavior, Caliper has two levels of diagnostic output.

Stack traces — set CALIPER_DEBUG=1 to see full stack traces on any error instead of just the message:

CALIPER_DEBUG=1 npx caliper check

Verbose API logging — use --verbose on AI review commands to see Claude API request and response details:

npx caliper 142 --verbose
npx caliper review --verbose

Pipeline trace — after a PR review completes, inspect the full pipeline trace for timing, costs, and step-by-step state:

npx caliper trace <pr-number>         # Summary + open trace.html
npx caliper trace <pr-number> --json  # Path to raw trace.json

Trace data is stored at /tmp/caliper/<pr-number>/trace.json.