Troubleshooting

Common issues and how to fix them

Troubleshooting

Solutions to common issues you might encounter with Claudear.

Linear Issues

ngrok Tunnel Not Starting

Symptoms:

• Error: "Failed to establish ngrok tunnel"
• No public URL in logs

Solutions:

1. Check ngrok auth token:

   ngrok config check
   

2. Verify token in .env:

   NGROK_AUTHTOKEN=your-token-here
   

3. Test ngrok manually:

   ngrok http 8000
   

4. Check ngrok status: Visit status.ngrok.com

Webhook Events Not Received

Symptoms:

• Moving issues to Todo does nothing
• No events in Claudear logs

Solutions:

1. Verify webhook URL:

   • Must end with /webhooks/linear
   • Must use HTTPS

2. Check webhook secret:

   • Same value in Linear and .env
   • No trailing whitespace

3. Test the endpoint:

   curl https://your-url.ngrok.io/webhooks/linear/test
   

4. Check Linear webhook logs:

   • Go to Linear Settings → API → Webhooks
   • Click on your webhook
   • Check delivery history

Wrong State IDs

Symptoms:

• Issues not picked up
• State changes not detected

Solutions:

1. Verify state names match exactly:

   LINEAR_STATE_TODO=Todo  # Must match Linear exactly
   

2. Check case sensitivity:

   • Linear state names are case-sensitive

Notion Issues

Tasks Not Being Picked Up

Symptoms:

• Pages moved to Todo are ignored
• No polling activity in logs

Solutions:

1. Verify database is shared with integration:

   • Open database → ... → Add connections
   • Check "Claudear" is listed

2. Check status value matches:

   • Claudear auto-detects common names (Todo, In Progress, Done)
   • For custom names, use NOTION_{DB}_STATUS_TODO=YourStatus

3. Verify database ID:

   # Check ID is correct (32 chars, no hyphens in env var name)
   NOTION_DATABASE_ID=abc123def456
   

4. Check polling is running:

   • Look for "Polling Notion database" in logs

Unauthorized Errors

Symptoms:

• "API token is invalid" errors
• 401 responses in logs

Solutions:

1. Check API key is valid:

   • Regenerate at notion.so/my-integrations

2. Verify database is shared:

   • Each database must explicitly add the integration

Properties Not Appearing

Symptoms:

• Claudear ID, Branch, etc. not showing on pages

Solutions:

1. Claudear creates properties on first task pickup
2. Trigger a task by moving a page to "Todo"
3. Check logs for property creation errors
4. Verify integration has "Update content" capability

Rate Limiting

Symptoms:

• 429 errors in logs
• Tasks not being picked up consistently

Solutions:

1. Increase poll interval:

   NOTION_POLL_INTERVAL=30
   

2. Reduce number of databases

Task Execution Issues

Claude Not Starting

Symptoms:

• Task stays in PENDING state
• No Claude Code output

Solutions:

1. Check Claude Code CLI:

   claude --version
   claude whoami
   

2. Verify authentication:

   claude auth status
   

3. Check worktree creation:

   ls -la /path/to/repo/.worktrees/
   

Tasks Keep Failing

Symptoms:

• Tasks immediately fail
• Error comments on tasks

Solutions:

1. Check the error message in the comment

2. Review logs:

   LOG_LEVEL=DEBUG claudear
   

3. 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:

1. Check git status:

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

2. Clean up stale worktrees:

   git worktree prune
   

3. Check disk space:

   df -h
   

Comments Not Detected

Symptoms:

• Blocked tasks don't resume
• Your comments are ignored

Solutions:

1. Check comment polling:

   COMMENT_POLL_INTERVAL=10  # More frequent polling
   

2. Verify you're commenting as yourself:

   • Comments from bots/integrations may be ignored

Multi-Provider Issues

Wrong Repository Used

Symptoms:

• Task creates worktree in wrong repo
• PR created in wrong repo

Solutions:

1. Check per-instance repo paths:

   LINEAR_ENG_REPO=/correct/path/for/eng
   NOTION_ABC123_REPO=/correct/path/for/abc123
   

2. Verify team/database ID matches:

   • Check startup banner shows correct mappings

Database Schema Errors

Symptoms:

• "no such column: provider" errors
• SQLite errors on startup

Solutions:

1. Run migration:

   python -m claudear.scripts.migrate_db
   

2. Or delete and recreate:

   rm claudear.db
   claudear  # Creates fresh database
   

Performance Issues

High Memory Usage

Solutions:

1. Reduce concurrent tasks:

   MAX_CONCURRENT_TASKS=2
   

2. Check for stuck processes:

   ps aux | grep claude
   

Slow Task Startup

Solutions:

1. Pre-fetch base branch:

   cd /path/to/repo
   git fetch origin main
   

2. Use local base branch:

   • Ensure main is up to date locally

Getting Help

If none of these solutions work:

1. Enable debug logging:

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

2. Test the multi-provider setup:

   python -m claudear.scripts.test_multi_provider
   

3. Check GitHub Issues: github.com/ianborders/claudear/issues

4. Open a new issue with:

   • Debug logs (sanitized)
   • Steps to reproduce
   • Environment info (OS, Python version)