Troubleshooting Guide¶

This comprehensive guide helps you diagnose and resolve common issues with reviewtask.

Quick Diagnosis Commands¶

Start troubleshooting with these diagnostic commands:

# Check version and system info
reviewtask version

# Verify authentication
reviewtask auth status
reviewtask auth check

# Test basic functionality
reviewtask show
reviewtask status

Authentication Issues¶

Token Validation Failed¶

Symptoms: - "Authentication failed" errors - "Invalid token" messages - 401 Unauthorized errors

Solutions:

Check token validity:
```
reviewtask auth check
```
Verify token hasn't expired:
Check GitHub Settings > Developer settings > Personal access tokens
Look for expiration date and token status
Ensure correct scopes:
Private repos: Requires repo scope
Public repos: Requires public_repo scope
Organization repos: Requires read:org scope

Re-authenticate:

reviewtask auth logout
reviewtask auth login

Repository Access Denied¶

Symptoms: - "Repository not found" errors - "Access denied" when fetching PR data - 403 Forbidden errors

Solutions:

For private repositories:

# Ensure token has 'repo' scope
reviewtask auth check

For organization repositories:

# Ensure token has 'read:org' scope
# Check organization's third-party access settings

Verify repository URL:

git remote -v
# Ensure you're in the correct repository

Multiple Authentication Sources¶

Symptoms: - Confusion about which token is being used - Inconsistent authentication behavior

Diagnosis:

reviewtask auth status

Priority order: 1. GITHUB_TOKEN environment variable (highest) 2. Local config file (.pr-review/auth.json) 3. GitHub CLI (gh auth token) (lowest)

Solutions:

# Use specific source
export GITHUB_TOKEN="your_token"  # Environment variable

# Or remove conflicting sources
reviewtask auth logout            # Remove local config
unset GITHUB_TOKEN               # Remove environment variable

Rate Limit Issues¶

API Rate Limiting¶

Symptoms: - "Rate limit exceeded" errors - Slow or failing API requests - 429 Too Many Requests errors

Check current status:

reviewtask auth check

Rate limits: - Authenticated: 5,000 requests/hour - Unauthenticated: 60 requests/hour

Solutions: 1. Ensure authentication:

reviewtask auth status

Use caching:

# Avoid --refresh-cache unless necessary
reviewtask  # Uses cached data when possible

Wait for reset:
Rate limits reset every hour
Check X-RateLimit-Reset time in auth check output

Version and Update Issues¶

Binary Not Found¶

Symptoms: - "command not found: reviewtask" - "reviewtask: command not found"

Solutions:

Check installation:

which reviewtask
# Should show path to binary

Verify PATH:

echo $PATH
# Should include installation directory

Add to PATH:

# For bash/zsh
export PATH="$HOME/.local/bin:$PATH"

# For fish
set -gx PATH $HOME/.local/bin $PATH

Reinstall:

curl -fsSL https://raw.githubusercontent.com/biwakonbu/reviewtask/main/scripts/install/install.sh | bash -s -- --force

Version Issues¶

Symptoms: - Old version behavior - Missing features - Update failures

Solutions:

Check current version:
```
reviewtask version
```
Update to latest:
```
reviewtask version latest
```

Manual reinstall:

curl -fsSL https://raw.githubusercontent.com/biwakonbu/reviewtask/main/scripts/install/install.sh | bash -s -- --force

Task Generation Issues¶

Missing Tasks¶

Symptoms: - No tasks generated from PR reviews - Empty task lists despite review comments

Diagnosis:

# Enable verbose mode
# Edit .pr-review/config.json:
{
  "ai_settings": {
    "verbose_mode": true
  }
}

# Test specific phases
reviewtask debug fetch review 123
reviewtask debug fetch task 123

Solutions:

Force refresh:
```
reviewtask --refresh-cache
```
Check AI provider:
```
claude --version  # For Claude Code
```

Verify PR has reviews:

# Check on GitHub that PR actually has review comments

Inconsistent Task Generation¶

Symptoms: - Tasks appear and disappear - Duplicate tasks - Incorrect task content

Solutions:

Clear cache:
```
reviewtask --refresh-cache
```
Check comment changes:
Tasks are cancelled when comments change significantly
New tasks created for new/updated comments

Adjust deduplication:

{
  "ai_settings": {
    "deduplication_enabled": false,
    "similarity_threshold": 0.7
  }
}

Task Status Issues¶

Symptoms: - Task statuses reset unexpectedly - Cannot update task status - Status changes not persisting

Solutions:

Check task ID:

reviewtask show  # Get correct task UUID

Verify file permissions:

ls -la .pr-review/
# Ensure write permissions on task files

Manual status check:

cat .pr-review/PR-*/tasks.json
# Inspect task file directly

AI Provider Integration Issues¶

Claude Code Integration¶

Symptoms: - "claude command not found" - AI analysis failures - Empty or malformed task generation

Solutions:

Verify installation:
```
claude --version
which claude
```

Check PATH:

echo $PATH | grep -o '[^:]*claude[^:]*'

Install Claude Code: Follow official installation instructions
Test Claude integration:
```
reviewtask prompt claude pr-review
```

JSON Recovery Issues¶

Symptoms: - "unexpected end of JSON input" errors - Truncated responses - Malformed task data

Solutions:

Enable recovery:

{
  "ai_settings": {
    "enable_json_recovery": true,
    "max_recovery_attempts": 3,
    "log_truncated_responses": true
  }
}

Reduce prompt size:

{
  "ai_settings": {
    "validation_enabled": true,
    "max_retries": 5
  }
}

Check response analytics:
```
cat .pr-review/response_analytics.json
```

Cache and Performance Issues¶

Cache Problems¶

Symptoms: - Outdated task content - Missing new comments - Inconsistent behavior

Solutions:

Force refresh:
```
reviewtask --refresh-cache
```
Clear cache manually:
```
rm -rf .pr-review/cache/
reviewtask
```
Check cache permissions:
```
ls -la .pr-review/cache/
```

Performance Issues¶

Symptoms: - Slow processing - Timeouts - High memory usage

Solutions:

Check PR size:
```
reviewtask stats --pr 123
```
Enable optimization:
Tool automatically optimizes for large PRs
Uses parallel processing and chunking

Reduce processing load:

{
  "ai_settings": {
    "validation_enabled": false,
    "deduplication_enabled": false
  }
}

Configuration Issues¶

Invalid Configuration¶

Symptoms: - Tool ignores configuration changes - Default behavior instead of custom settings - JSON parsing errors

Solutions:

Validate JSON syntax:
```
cat .pr-review/config.json | jq .
```

Reset to defaults:

reviewtask init  # Recreates default config

Check file permissions:
```
ls -la .pr-review/config.json
```

Priority Assignment Issues¶

Symptoms: - All tasks get same priority - Priority rules not working - Unexpected priority assignments

Solutions:

Enable verbose mode:

{
  "ai_settings": {
    "verbose_mode": true
  }
}

Review priority rules:

{
  "priority_rules": {
    "critical": "Security vulnerabilities, authentication bypasses",
    "high": "Performance bottlenecks, memory leaks",
    "medium": "Functional bugs, logic improvements",
    "low": "Code style, naming conventions"
  }
}

Test with simple rules:
Start with clear, distinct priority descriptions
Add complexity gradually

Network and Connectivity Issues¶

GitHub API Issues¶

Symptoms: - Connection timeouts - Intermittent failures - "Network unreachable" errors

Solutions:

Check GitHub status:
Visit GitHub Status
Verify GitHub API is operational

Test connectivity:

curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Use retry logic:
Tool includes automatic retry for transient failures
Enable verbose mode to see retry attempts

Proxy and Firewall Issues¶

Symptoms: - Connection failures in corporate environments - SSL certificate errors - Blocked requests

Solutions:

Configure proxy:

export HTTPS_PROXY=https://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

Check firewall rules:
Ensure access to api.github.com
Verify HTTPS (443) is allowed

Debug Mode and Logging¶

Enable Verbose Output¶

For detailed troubleshooting, enable verbose mode:

{
  "ai_settings": {
    "verbose_mode": true,
    "log_truncated_responses": true
  }
}

Debug Commands¶

Test specific functionality:

# Test review fetching only
reviewtask debug fetch review 123

# Test task generation only  
reviewtask debug fetch task 123

# Both commands enable verbose mode automatically

Log Analysis¶

Check log output for: - API request/response details - Task generation process - Error messages and stack traces - Performance metrics

Getting Additional Help¶

Self-Diagnosis Checklist¶

✅ Authentication working? reviewtask auth check
✅ Latest version? reviewtask version
✅ Valid configuration? cat .pr-review/config.json | jq .
✅ AI provider available? claude --version
✅ Repository access? Can you see PR on GitHub?
✅ Cache cleared? Try reviewtask --refresh-cache

When to Seek Help¶

Open a GitHub issue if: - Self-diagnosis doesn't resolve the issue - You encounter unexpected behavior - You have feature requests or suggestions - Documentation is unclear or incomplete

Issue Report Template¶

When reporting issues, include:

**Environment:**
- reviewtask version: `reviewtask version`
- Operating system: 
- AI provider: Claude Code version X.X.X

**Problem:**
- Clear description of the issue
- Steps to reproduce
- Expected vs actual behavior

**Logs:**
- Enable verbose mode and include relevant log output
- Sanitize any sensitive information (tokens, private repo names)

**Configuration:**
- Include .pr-review/config.json (sanitized)
- Mention any custom settings

For more help: - GitHub Issues - Command Reference - Configuration Guide