---
title: Troubleshooting
description: Common issues and how to fix them
section: Usage
order: 7
---

# 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:**
   ```bash
   ngrok config check
   ```

2. **Verify token in .env:**
   ```bash
   NGROK_AUTHTOKEN=your-token-here
   ```

3. **Test ngrok manually:**
   ```bash
   ngrok http 8000
   ```

4. **Check ngrok status:** Visit [status.ngrok.com](https://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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   NOTION_STATUS_TODO=ToDo  # Must match exactly
   ```

3. **Verify database ID:**
   ```bash
   # 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:**
   ```bash
   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:**
   ```bash
   claude --version
   claude whoami
   ```

2. **Verify authentication:**
   ```bash
   claude auth status
   ```

3. **Check worktree creation:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   cd /path/to/repo
   git status
   git worktree list
   ```

2. **Clean up stale worktrees:**
   ```bash
   git worktree prune
   ```

3. **Check disk space:**
   ```bash
   df -h
   ```

### Comments Not Detected

**Symptoms:**
- Blocked tasks don't resume
- Your comments are ignored

**Solutions:**

1. **Check comment polling:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   python -m claudear.scripts.migrate_db
   ```

2. **Or delete and recreate:**
   ```bash
   rm claudear.db
   claudear  # Creates fresh database
   ```

## Performance Issues

### High Memory Usage

**Solutions:**

1. **Reduce concurrent tasks:**
   ```bash
   MAX_CONCURRENT_TASKS=2
   ```

2. **Check for stuck processes:**
   ```bash
   ps aux | grep claude
   ```

### Slow Task Startup

**Solutions:**

1. **Pre-fetch base branch:**
   ```bash
   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:**
   ```bash
   LOG_LEVEL=DEBUG claudear 2>&1 | tee debug.log
   ```

2. **Test the multi-provider setup:**
   ```bash
   python -m claudear.scripts.test_multi_provider
   ```

3. **Check GitHub Issues:**
   [github.com/ianborders/claudear/issues](https://github.com/ianborders/claudear/issues)

4. **Open a new issue** with:
   - Debug logs (sanitized)
   - Steps to reproduce
   - Environment info (OS, Python version)
