Troubleshooting

Common failure modes and how to resolve them.

"kew run picks no issue"

kew queries GitHub for issues with the ready label. If nothing is picked:

1. Check labels — verify the issue has the ready label and a priority label (p0-critical through p3-low):

   gh issue list --label ready
   

2. Check authentication — ensure gh is authenticated and can access the repo:

   gh auth status
   

3. Check config — verify project.repo in kew.toml matches your repository, or that gh auto-detects it correctly:

   kew run --dry-run
   

4. Already in-progress — issues labeled in-progress or agent-working are excluded from selection. Check if the issue is already being worked on.

"Agent times out"

The agent is killed after agent.timeout_minutes (default: 120 minutes). If your agent consistently times out:

1. Increase the timeout — set a higher value in kew.toml:

   [agent]
   timeout_minutes = 180
   

2. Check the complexity label — complex issues get more token budget guidance but still respect the timeout. Consider breaking the issue into smaller pieces.
3. Check the issue scope — issues that touch many files or require cross-cutting changes are more likely to time out. Use the simple / medium / complex labels to set expectations.

"Budget exceeded"

kew enforces per-issue, daily, and weekly spend caps configured in [budget].

1. Check current spend:

   kew status --cost
   

2. Increase limits — adjust [budget] in kew.toml:

   [budget]
   per_issue_usd = 20.0
   daily_usd = 100.0
   weekly_usd = 400.0
   

3. Force past the check — use --force to bypass budget checks for a single run:

   kew run --force --issue 42
   

4. Per-run cap — the per-run cap (agent.max_budget_usd) is separate from the aggregate budget. Increase it if individual runs are hitting the limit:

   [agent]
   max_budget_usd = 15.0
   

"Worktree already exists"

A stale worktree can remain after a crash or interrupted dispatch. kew creates worktrees at {branches.worktree_base}/agent/issue-{N}.

1. List worktrees:

   git worktree list
   

2. Remove the stale worktree:

   git worktree remove .worktrees/agent/issue-42
   

3. Force removal if the directory is corrupted:

   git worktree remove --force .worktrees/agent/issue-42
   

4. Prune all stale entries (safe — only removes worktrees whose directories no longer exist):

   git worktree prune