Troubleshooting

Common issues and solutions when using the release notes automation.

Installation issues

Python command not found

Problem: python: command not found or python3: command not found

Solutions:

Check if Python is installed:
```
which python3
python3 --version
```
Install Python:
macOS: brew install python3
Ubuntu or Debian: sudo apt-get install python3
Windows: Download from python.org

Use full path:

/usr/bin/python3 generate_release_notes.py --help

Virtual environment activation fails

Problem (Windows): cannot be loaded because running scripts is disabled

Solution:

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem (macOS or Linux): source: command not found

Solution:

# Use the correct shell activation
source venv/bin/activate  # bash or zsh
. venv/bin/activate       # alternative

Module import errors

Problem: ModuleNotFoundError: No module named 'anthropic'

Checklist:

Verify virtual environment is activated:

which python
# Should show path ending in /venv/bin/python

Reinstall dependencies:

pip install --upgrade pip
pip install -r requirements.txt

Check Python version:
```
python --version  # Must be 3.8+
```
Verify installation:
```
pip list | grep anthropic
```

Configuration issues

Invalid API key

Problem: 401 Unauthorized or Invalid API key

Solutions:

Check for extra spaces:

# Bad: "sk-ant-123 " (trailing space)
# Good: "sk-ant-123"

Verify correct provider:

# Make sure this matches your key type
ai_provider: "anthropic"  # for sk-ant-* keys
ai_provider: "openai"     # for sk-* keys (OpenAI)

Check key is active:
Log into your AI provider console
Verify key has not been revoked
Check billing is set up (after free tier)
Regenerate key:
Create a new API key
Update config.yaml
Try again

GitHub authentication failed

Problem: Bad credentials or 401 when accessing GitHub

Solutions:

Verify token format:

github_token: "ghp_xxxxxxxxxxxx"  # Classic token
github_token: "github_pat_xxxxx"  # Fine-grained token

Check token scopes:
For private repos: Need repo scope
For public repos: Need public_repo scope
Go to github.com/settings/tokens to verify
Token expiration:
Check if token has expired
Generate new token if needed

Repository access:

# Test access
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/repos/OWNER/REPO

Configuration file not found

Problem: FileNotFoundError: ../config.yaml

Solutions:

Check current directory:

pwd  # Should be in 01-release-notes-automation/
ls ../config.yaml  # Should exist

Create from example:

cd ..  # Go to repository root
cp config.example.yaml config.yaml

Use explicit path:

python generate_release_notes.py \
  --config /full/path/to/config.yaml \
  --repo owner/repo \
  --since 2024-01-01

Runtime issues

No commits found

Problem: Found 0 commits even though commits exist

Solutions:

Check date range:

# Make sure date is in the past
--since 2024-01-01

# Not future dates
--since 2025-12-31  # Won't find anything

Verify repository access:

# Can you access the repo?
python -c "
from github import Github
import yaml
config = yaml.safe_load(open('config.yaml'))
g = Github(config['github_token'])
repo = g.get_repo('owner/repo')
print(f'Repo: {repo.name}')
print(f'Commits: {repo.get_commits().totalCount}')
"

Check repository name:

# Correct format
--repo octocat/Hello-World  # owner/repo

# Incorrect formats
--repo Hello-World          # Missing owner
--repo github.com/octocat/Hello-World  # Include domain

Private repository:
Verify token has repo scope
Verify you have access to the repository

Rate limit exceeded

Problem: API rate limit exceeded

GitHub rate limits:

Authenticated: 5,000 requests per hour
Unauthenticated: 60 requests per hour

Solutions:

Wait for reset:

# Check when rate limit resets
python -c "
from github import Github
import yaml
config = yaml.safe_load(open('config.yaml'))
g = Github(config['github_token'])
rate = g.get_rate_limit()
print(f'Remaining: {rate.core.remaining}')
print(f'Resets at: {rate.core.reset}')
"

Reduce date range:

# Instead of --since 2023-01-01 (lots of commits)
# Try --since 2024-01-01 (fewer commits)

Use caching:
Script should cache commits between runs
Implemented in improved version

AI provider rate limits:

Check your provider documentation:

Anthropic: docs.anthropic.com/rate-limits
OpenAI: platform.openai.com/docs/guides/rate-limits

AI categorization errors

Problem: Commits consistently miscategorized

Solutions:

Review prompt quality:
Are examples clear?
Are definitions specific enough?
Are exclusions comprehensive?

Test with smaller set:

# Use date range with fewer commits to iterate faster
--since 2024-01-20 --until 2024-01-25

Check commit message quality:

# Poor: "fix bug"
# Good: "Fix memory leak in parser"

AI can only categorize based on commit message
Bad commit messages lead to bad categorization
Iterate on prompt:
See Prompt evolution
Add specific examples from your repository
Follow Tutorial step 5

Output file permission denied

Problem: PermissionError: [Errno 13] Permission denied: 'release_notes.md'

Solutions:

Check if file is open:
Close file in your text editor
Try again

Check file permissions:

ls -l release_notes.md
chmod 644 release_notes.md

Use different output file:
```
--output release_notes_new.md
```

Output quality issues

Internal changes appearing

Problem: CI or CD, test, or internal changes in output

Solution: Refine exclusion rules in prompt

Exclusions:
- Commits containing: "internal", "ci:", "test:"
- Commits from paths: /tests/, /.github/
- By author: dependabot[bot]

See Prompt engineering reference

Features versus enhancements confused

Problem: Improvements categorized as features

Solution: Add clearer examples in prompt

New Features: "Add" + "wholly new capability"
Examples: "Add user authentication" (Correct)
Not: "Add performance improvement" (Enhancement)

Enhancements: "Improve", "Update", "Optimize"
Examples: "Improve search performance" (Correct)

Missing contextual information

Problem: Output is accurate but lacks business context

Solution: This is expected.

The automation provides accurate categorization. Human review adds:

Business value explanations
Links to documentation
Context for non-technical readers
Emphasis on important changes

Time savings still significant: 90 minutes to 15 minutes

Performance issues

Script runs very slowly

Problem: Takes more than 5 minutes for small repository

Checklist:

Check internet connection
Verify API provider status
Anthropic: status.anthropic.com
OpenAI: status.openai.com
GitHub: githubstatus.com

Reduce commit count:

# Narrow date range
--since 2024-01-20 --until 2024-01-31

Check rate limiting:
May be throttled by provider
Wait and retry

High AI API costs

Problem: Unexpectedly high API bills

Solutions:

Check model selection:

# More expensive
model: "claude-3-opus-20240229"    # Higher cost
model: "gpt-4"                     # Higher cost

# Cost-effective
model: "claude-3-sonnet-20240229"  # Moderate cost
model: "gpt-3.5-turbo"             # Lower cost

Batch requests:
Process multiple releases at once
Do not run for every commit
Set budget alerts:
Anthropic: Console → Billing → Budget Alerts
OpenAI: Console → Usage → Limits

Get help

If you are still stuck:

1. Check documentation

FAQ - Common questions
Tutorial - Step-by-step guide
Examples - Real-world cases

2. Review error messages

Enable verbose output:

python generate_release_notes.py \
  --repo owner/repo \
  --since 2024-01-01 \
  --verbose  # Add if available

3. Search issues

Check if others have encountered this:

GitHub issues

4. Ask for help

Create a new issue with:

Error message (full text)
Steps to reproduce
Your environment (OS, Python version)
Relevant configuration (with API keys removed)

Do not share:

API keys
GitHub tokens
Private repository details

Open an issue if you are still having issues.