Troubleshooting¶

Common issues and solutions for mcpbr.

Docker Issues¶

Docker Not Running¶

Symptom: Error connecting to Docker daemon

Solution:

open -a Docker
# Wait for Docker to start, then verify
docker info

sudo systemctl start docker
docker info

docker info

Pre-built Image Not Found¶

Symptom: Warning about falling back to building from scratch

Solution: This is normal for some tasks. You can manually pull:

docker pull ghcr.io/epoch-research/swe-bench.eval.x86_64.astropy__astropy-12907

Or disable pre-built images to always build from scratch:

mcpbr run -c config.yaml --no-prebuilt

Orphaned Containers¶

Symptom: Old mcpbr containers consuming resources

Solution:

# Preview what would be removed
mcpbr cleanup --dry-run

# Remove orphaned containers
mcpbr cleanup

Performance Issues¶

Slow on Apple Silicon¶

Symptom: Tasks take much longer than expected on M1/M2/M3 Macs

Explanation: mcpbr uses x86_64 Docker images that run via emulation on ARM64.

Solutions:

1. Install Rosetta 2 for better emulation:

   softwareupdate --install-rosetta
   

2. Reduce concurrency to avoid resource contention:

   max_concurrent: 2
   

3. Increase timeouts:

   timeout_seconds: 600
   

Task Timeouts¶

Symptom: Tasks fail with "Timeout" error

Solutions:

1. Increase timeout in config:

   timeout_seconds: 600  # 10 minutes
   

2. Reduce max iterations if agent is looping:

   max_iterations: 20
   

3. Use a faster model for testing:

   model: "haiku"
   

API Issues¶

API Key Not Set¶

Symptom: "ANTHROPIC_API_KEY environment variable not set"

Solution:

export ANTHROPIC_API_KEY="sk-ant-..."

Add to your shell profile (.bashrc, .zshrc) for persistence.

API Key Invalid¶

Symptom: Authentication errors from Anthropic API

Solutions:

1. Verify the key format (should start with sk-ant-):

   echo $ANTHROPIC_API_KEY
   

2. Check key permissions in Anthropic Console

3. Ensure no extra whitespace:

   export ANTHROPIC_API_KEY="sk-ant-..." # No spaces
   

Rate Limiting¶

Symptom: API rate limit errors

Solutions:

1. Reduce concurrency:

   max_concurrent: 2
   

2. Add delays between tasks (requires code modification)

3. Check your API tier limits in Anthropic Console

CLI Issues¶

Claude CLI Not Found¶

Symptom: "Claude Code CLI (claude) not found in PATH"

Solution:

# Install Claude CLI
npm install -g @anthropic-ai/claude-code

# Verify installation
which claude

If installed but not found, check your PATH includes npm global binaries:

export PATH="$PATH:$(npm config get prefix)/bin"

Command Not Found: mcpbr¶

Symptom: "mcpbr: command not found"

Solutions:

1. Ensure mcpbr is installed:

   pip install mcpbr
   

2. Check it's in your PATH:

   pip show mcpbr | grep Location
   

3. Use the full path or module:

   python -m mcpbr --help
   

MCP Server Issues¶

Server Not Starting¶

Symptom: "Warning: MCP server add failed"

Solutions:

1. Test the server independently:

   npx -y @modelcontextprotocol/server-filesystem /tmp/test
   

2. Check environment variables:

   echo $SUPERMODEL_API_KEY  # If using Supermodel
   

3. Verify the command exists:

   which npx  # or python, node, etc.
   

Tools Not Appearing¶

Symptom: MCP tools not being used by the agent

Possible causes:

1. Server not registering tools correctly
2. Tool descriptions unclear
3. Built-in tools sufficient for the task

Debug steps:

1. Enable verbose logging:

   mcpbr run -c config.yaml -vv --log-dir logs/
   

2. Check per-instance logs for tool registration

3. Review tool_usage in results JSON

Evaluation Issues¶

Patch Not Applying¶

Symptom: "Patch does not apply" error

Explanation: The agent's changes don't apply cleanly to the original repository state.

This can happen when:

• Agent modified files that conflict with test patches
• Agent created files instead of modifying existing ones
• Git state is inconsistent

Note: This is often an agent behavior issue, not an mcpbr bug.

Tests Failing¶

Symptom: Tests fail even though patch applies

Debug steps:

1. Check per-instance logs for test output:

   cat logs/instance_id_mcp_*.json | jq '.events[-5:]'
   

2. Review the fail_to_pass results in JSON output

3. The agent may have made an incorrect fix

No Patch Generated¶

Symptom: "No changes made by Claude Code"

Possible causes:

1. Agent didn't find a solution
2. Agent made changes then reverted them
3. Max iterations reached without completing

Solutions:

1. Increase max_iterations:

   max_iterations: 30
   

2. Review logs to understand agent behavior

Getting Help¶

Gathering Debug Information¶

When reporting issues, include:

# Version info
mcpbr --version
python --version
docker --version

# Environment
echo $ANTHROPIC_API_KEY | head -c 10  # First 10 chars only

# Run with verbose logging
mcpbr run -c config.yaml -n 1 -vv --log-dir debug-logs/

Where to Get Help¶

• GitHub Issues - Bug reports
• GitHub Discussions - Questions

Common Log Locations¶