264 lines
4.9 KiB
Markdown
264 lines
4.9 KiB
Markdown
# 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
|
|
|
|
### @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:
|
|
```yaml
|
|
python main.py comment owner/repo 123 "@ai-bot ..."
|
|
```
|
|
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)
|