Troubleshooting

This page covers common issues and their solutions when using Bop.

Installation Issues

“command not found: bop”

The bop binary isn’t in your PATH.

Solution:

For Homebrew installs, verify installation:

1

brew list delightfulhammers/tap/bop

For manual installs, ensure the binary is in a directory in your PATH:

1
2
3
4
5

# Check current PATH
echo $PATH

# Move binaries to a directory in PATH
sudo mv bop bop-mcp /usr/local/bin/

Permission denied on Linux

Solution:

1

chmod +x bop bop-mcp

API Key Issues

“No LLM provider configured”

No API keys are set for any provider.

Solution:

Set at least one API key:

1
2
3
4
5

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."
# or
export GEMINI_API_KEY="..."

“Invalid API key” or “Authentication failed”

The API key is malformed or expired.

Solution:

1. Verify the key format:

   • Anthropic keys start with sk-ant-
   • OpenAI keys start with sk-

2. Check for trailing whitespace:

   1	echo "[$ANTHROPIC_API_KEY]" # Should show key without extra spaces

3. Regenerate the key from the provider’s dashboard

“Rate limit exceeded”

You’ve hit the provider’s rate limit.

Solution:

1. Wait and retry (limits reset periodically)
2. Use multiple providers to distribute load:

   1 2 3

   export ANTHROPIC_API_KEY="..." export OPENAI_API_KEY="..." export GEMINI_API_KEY="..."

3. Configure rate limiting in your provider account

“Insufficient quota” or “Billing required”

Your API account doesn’t have credits or billing isn’t set up.

Solution:

1. Add billing/credits to your provider account
2. Check usage dashboards for current consumption

GitHub Integration Issues

“Resource not accessible by integration”

The GitHub token lacks required permissions.

Solution:

For personal access tokens, ensure repo scope is enabled.

For GitHub Actions, add permissions to your workflow:

1
2
3

permissions:
  contents: read
  pull-requests: write

“Not found” when reviewing PR

The PR doesn’t exist or token can’t access it.

Solution:

1. Verify the PR exists and number is correct
2. For private repos, ensure your token has access
3. Check the owner/repo are correct:

   1 2 3 4

   # These should all work bop review pr 123 bop review pr owner/repo#123 bop review pr https://github.com/owner/repo/pull/123

“Could not resolve to a Repository”

The repository reference is invalid.

Solution:

1. Check spelling of owner and repo names
2. Verify the repository exists
3. Ensure your token has access to the repository

“Validation failed” when posting comments

The comment couldn’t be posted, often due to line number issues.

Solution:

This can happen when:

• The file was deleted in the PR
• The line number is outside the diff
• The commit SHA changed

Bop handles most of these automatically, but if it persists, check that the PR hasn’t been force-pushed since the review started.

Review Issues

Timeout during review

Large PRs can timeout during LLM processing.

Solution:

1. Increase timeout in configuration:

   1 2 3

   providers: anthropic: timeout: 300s # 5 minutes

2. Use faster models:

   1 2 3 4

   reviewers: quick: provider: gemini model: gemini-3-flash-preview

3. Split large PRs into smaller ones

4. For GitHub Actions, increase job timeout:

   1 2 3

   jobs: review: timeout-minutes: 30

No findings generated

The review completed but found nothing.

Possible causes:

1. Only non-code files changed: Bop focuses on code changes
2. Redaction filtered everything: Check redaction settings
3. Review instructions too restrictive: Review custom instructions
4. Small changes: Minor changes may not trigger findings

Debug:

1

BOP_LOG_LEVEL=debug bop review branch

Too many false positives

The review is generating low-quality findings.

Solution:

1. Enable verification:

   1 2 3 4 5 6

   verification: enabled: true depth: thorough confidence: critical: 90 high: 80

2. Adjust reviewer personas to be more specific

3. Use the --instructions flag to guide reviews:

   1	bop review branch --instructions "Focus only on security issues. Ignore style."

Duplicate findings

The same issue appears multiple times.

Solution:

Enable semantic deduplication:

1
2
3
4

deduplication:
  semantic:
    enabled: true
    lineThreshold: 10

MCP Server Issues

Tools not appearing in Claude Code/Cursor

The MCP server isn’t loading correctly.

Solution:

1. Verify bop-mcp is in your PATH:

   1	which bop-mcp

2. Check your MCP configuration file syntax

3. Restart your editor/AI tool

4. Check for errors in MCP logs (varies by tool)

“Missing GITHUB_TOKEN” in MCP

The MCP server needs a GitHub token for PR operations.

Solution:

Add the token to your MCP configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "mcpServers": {
    "bop": {
      "command": "bop-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

MCP tool calls failing silently

The tool is being called but returning empty or error results.

Solution:

1. Check environment variables are passed correctly
2. Verify API keys in MCP configuration
3. Test the CLI directly to isolate the issue:

   1	bop review pr owner/repo#123

Configuration Issues

Config file not loading

Your bop.yaml settings aren’t being applied.

Solution:

1. Check file location (project root or ~/.config/bop/)
2. Verify YAML syntax:

   1 2	# Check for YAML errors cat bop.yaml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"

3. Check file permissions (must be readable)
4. Enable debug logging to see config loading:

   1	BOP_LOG_LEVEL=debug bop review branch

Environment variable not working

The BOP_* environment variable isn’t being applied.

Solution:

1. Verify the variable name matches the config path exactly:

   • Config: review.blockThreshold
   • Env: BOP_REVIEW_BLOCKTHRESHOLD

2. Check the variable is exported:

   1 2 3

   export BOP_REVIEW_BLOCKTHRESHOLD=medium # not just BOP_REVIEW_BLOCKTHRESHOLD=medium

3. Remember priority: CLI flags > env vars > config file

Git Issues

“Not a git repository”

Bop was run outside a Git repository.

Solution:

Navigate to a Git repository or specify one:

1
2

cd /path/to/repo
bop review branch

“Could not find base ref”

The base branch doesn’t exist.

Solution:

1. Check the branch name:

   1	git branch -a

2. Specify the correct base:

   1	bop review branch --base develop

3. Fetch from remote:

   1	git fetch origin main

“No changes between branches”

There’s nothing to review.

Solution:

1. Verify you’re on the correct branch:

   1	git branch --show-current

2. Check for uncommitted changes (if using --include-uncommitted)

3. Verify there are actual differences:

   1	git diff main..HEAD

Getting Help

If you’re still stuck:

1. Check logs: Run with BOP_LOG_LEVEL=debug
2. Version info: Run bop --version
3. Submit feedback: bop feedback
4. GitHub issues: Report bugs at the project repository