openrabbit/docs/troubleshooting.md

Troubleshooting

Common issues and solutions for the AI Code Review system.

Installation Issues

ModuleNotFoundError: No module named 'requests'

Install dependencies:

pip install requests pyyaml

ImportError: cannot import name 'BaseAgent'

Ensure you're running from the correct directory:

cd tools/ai-review
python main.py pr owner/repo 123

---

Authentication Issues

repository not found

Causes:

• Bot token lacks access to the repository
• Repository path is incorrect

Solutions:

1. Verify token has repo permissions
2. Check repository path format: owner/repo
3. Ensure token can access both the target repo and the AI tooling repo

401 Unauthorized

Causes:

• Invalid or expired token
• Missing token in environment

Solutions:

1. Regenerate the bot token
2. Verify AI_REVIEW_TOKEN is set correctly
3. Check organization secret scope is "All Repositories"

403 Forbidden

Causes:

• Token lacks write permissions
• Repository is private and token doesn't have access

Solutions:

1. Ensure token has issue:write permission
2. Add bot account as collaborator to private repos

---

LLM Issues

OPENAI_API_KEY not set

Set the environment variable:

export OPENAI_API_KEY="sk-..."

Or in workflow:

env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Rate limit exceeded

Causes:

• Too many requests to LLM provider
• API quota exhausted

Solutions:

1. Increase rate limit interval in config
2. Switch to a different provider temporarily
3. Check your API plan limits

JSON decode error from LLM

Causes:

• LLM returned non-JSON response
• Response was truncated

Solutions:

1. Increase max_tokens in config
2. Check LLM response in logs
3. Improve prompt to enforce JSON output

---

Workflow Issues

Workflow doesn't trigger

Causes:

• Workflow file not in correct location
• Event type not configured

Solutions:

1. Ensure workflow is in .gitea/workflows/
2. Check event types match your needs:

   on:
     pull_request:
       types: [opened, synchronize]
   

3. Verify Gitea Actions is enabled for the repository

review.py not found

Causes:

• Central repo checkout failed
• Path is incorrect

Solutions:

1. Verify the checkout step has correct repository and path
2. Check bot token has access to the AI tooling repo
3. Ensure path matches: .ai-review/tools/ai-review/main.py

PR comments not appearing

Causes:

• Token lacks issue write permission
• API URL is incorrect

Solutions:

1. Check AI_REVIEW_API_URL is correct
2. Verify token has issue:write permission
3. Check workflow logs for API errors

@ai-bot edits the issue instead of replying

Causes:

• Workflow is using the wrong CLI command for comments
• event_type is incorrectly set to "issues"

Solutions:

1. Ensure your workflow uses the comment command for mentions:

   python main.py comment owner/repo 123 "@ai-bot ..."
   

2. Verify you have separate jobs for issues vs issue_comment events (see Workflows)

---

Label Issues

Labels not being applied

Causes:

• Labels don't exist in repository
• Label names don't match config

Solutions:

1. Create labels matching your config:
   • priority: high
   • type: bug
   • ai-approved
2. Or update config to match existing labels:

   labels:
     priority:
       high: "P0"  # Your label name
   

label not found error

The agent gracefully handles missing labels. Create labels manually or disable auto-labeling:

agents:
  issue:
    auto_label: false

---

Performance Issues

Reviews are slow

Causes:

• Large diffs taking long to process
• LLM response time

Solutions:

1. Reduce max diff lines:

   review:
     max_diff_lines: 500
   

2. Use a faster model:

   model:
     openai: gpt-4.1-mini  # Faster than gpt-4
   

3. Consider Ollama for local, faster inference

Timeout errors

Increase timeout in API calls or use async processing:

client = GiteaClient(timeout=60)  # Increase from default 30

---

Debugging

Enable verbose logging

python main.py -v pr owner/repo 123

Check workflow logs

1. Go to repository -> Actions
2. Click on the failed workflow run
3. Expand job steps to see output

Test locally

# Set environment variables
export AI_REVIEW_TOKEN="your_token"
export AI_REVIEW_API_URL="https://your-gitea/api/v1"
export OPENAI_API_KEY="sk-..."

# Run locally
cd tools/ai-review
python main.py pr owner/repo 123

Validate Python syntax

python -m py_compile main.py

---

Getting Help

1. Check the documentation
2. Search existing issues in the repository
3. Create a new issue with:
   • Steps to reproduce
   • Error messages
   • Environment details (Gitea version, Python version)