Troubleshooting

Common issues and how to fix them

Troubleshooting

Solutions to common issues you might encounter with Clotion.

Connection Issues

Can't Connect to Notion

Symptoms:

Error: "Could not find database"
Error: "Invalid API key"
No tasks being picked up

Solutions:

Check API key:

# Verify it starts with secret_
echo $NOTION_API_KEY

Verify database ID:
- Open your database in Notion
- Check the URL for the 32-character ID
- Ensure no extra characters or hyphens
Check integration access:
- Open your database
- Click ... → Add connections
- Verify your integration is listed
Test the connection:
```
clotion test-connection
```

Tasks Not Being Picked Up

Symptoms:

Moving cards to Todo does nothing
No activity in Clotion logs

Solutions:

Verify status names match:

# In .env, must match Notion exactly
NOTION_STATUS_TODO=Todo  # Case-sensitive!

Check polling is running:
- Look for [INFO] Polling... in logs
- Increase log level: LOG_LEVEL=DEBUG
Verify the card:
- Has a title (required)
- Status is exactly "Todo"
- Is in the correct database

Task Execution Issues

Claude Not Starting

Symptoms:

Task stays in PENDING state
No Claude Code output

Solutions:

Check Claude Code CLI:
```
claude --version
claude whoami
```
Verify authentication:
```
claude auth status
```
Check worktree creation:
```
ls -la /path/to/repo/.worktrees/
```

Tasks Keep Failing

Symptoms:

Tasks immediately fail
Blocked checkbox gets checked with error

Solutions:

Check the error in the Current Status property
Review logs:
```
LOG_LEVEL=DEBUG clotion
```
Common causes:
- Missing dependencies in target repo
- Git configuration issues
- Insufficient permissions

Worktree Creation Fails

Symptoms:

Error: "Failed to create worktree"
Git errors in logs

Solutions:

Check git status:

cd /path/to/repo
git status
git worktree list

Clean up stale worktrees:
```
git worktree prune
```
Check disk space:
```
df -h
```

Notion Integration Issues

Properties Not Updating

Symptoms:

Status changes but other properties stay empty
Current Status not updating

Solutions:

Verify properties exist:
- Open database settings
- Check for: Blocked, Current Status, Clotion ID, Branch, PR URL
Re-run Clotion:
- Stop and restart
- Properties are verified/created on startup
Check property types:
- Blocked must be Checkbox
- Others must be Text or URL

Comments Not Detected

Symptoms:

Blocked tasks don't resume
Your comments are ignored

Solutions:

Check comment polling:

COMMENT_POLL_INTERVAL=10  # More frequent polling

Verify comment location:
- Comments must be on the card itself
- Not in the description
Manual unblock:
```
clotion unblock CLO-123
```

Wrong Status Values

Symptoms:

Cards not detected at correct status
State changes not working

Solutions:

Check exact status names:
- Open your database
- Click the Status property
- Copy exact names (including capitalization)

Update .env:

NOTION_STATUS_TODO=To Do  # If yours has a space

Performance Issues

High Memory Usage

Solutions:

Reduce concurrent tasks:
```
MAX_CONCURRENT_TASKS=2
```
Check for stuck processes:
```
ps aux | grep claude
```

Slow Polling

Solutions:

Adjust poll interval:
```
POLL_INTERVAL=5  # Faster polling
```
Note: Notion API has rate limits (3 requests/second)

Slow Task Startup

Solutions:

Pre-fetch base branch:
```
cd /path/to/repo
git fetch origin main
```
Use local base branch:
- Ensure main is up to date locally

Database Issues

Corrupted Database

Symptoms:

SQLite errors in logs
Tasks not persisting

Solutions:

Backup and recreate:

mv clotion.db clotion.db.backup
clotion  # Creates fresh database

Check file permissions:
```
ls -la clotion.db
```

Getting Help

If none of these solutions work:

Enable debug logging:

LOG_LEVEL=DEBUG clotion 2>&1 | tee debug.log

Check GitHub Issues: github.com/ianborders/clotion/issues
Open a new issue with:
- Debug logs (sanitized)
- Steps to reproduce
- Environment info (OS, Python version)