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 caliper from inside a git repo
Cost warning exceeds threshold	Adjust costWarningThreshold in .caliper/config.yaml (default: $2)

Set CALIPER_DEBUG=1 to show full stack traces on errors.