openrabbit/docs/troubleshooting.md

# Troubleshooting

Common issues and solutions for the AI Code Review system.

## Installation Issues

### `ModuleNotFoundError: No module named 'requests'`

Install dependencies:

```bash
pip install requests pyyaml
```

### `ImportError: cannot import name 'BaseAgent'`

Ensure you're running from the correct directory:

```bash
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:

```bash
export OPENAI_API_KEY="sk-..."
```

Or in workflow:

```yaml
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:
   ```yaml
   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

### @codebot 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:
   ```yaml
   python main.py comment owner/repo 123 "@codebot ..."
   ```
2. Verify you have separate jobs for `issues` vs `issue_comment` events (see [Workflows](workflows.md))

---

## 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:
   ```yaml
   labels:
     priority:
       high: "P0"  # Your label name
   ```

### `label not found` error

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

```yaml
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:
   ```yaml
   review:
     max_diff_lines: 500
   ```
2. Use a faster model:
   ```yaml
   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:

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

---

## Debugging

### Enable verbose logging

```bash
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

```bash
# 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

```bash
python -m py_compile main.py
```

---

## Getting Help

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