Troubleshooting

Environment Issues

Claude Code not found

which claude
claude --version

# Reinstall
npm install -g @anthropic-ai/claude-code

GitHub auth failed

gh auth status
gh auth login

# Use gh token as PAT if needed
export GITHUB_PAT=$(gh auth token)

Check all required variables

env | grep -E "(GITHUB|ANTHROPIC|CLAUDE)"

ADW Execution Issues

"Agent execution failed"

The most common issue — Claude Code encountered an error in execution.

# Read the raw output
cat agents/<adw-id>/sdlc_planner/raw_output.jsonl | python3 -m json.tool | tail -50

# Enable debug mode and re-run
export ADW_DEBUG=true
uv run adw_plan_build.py <issue>

"Missing plan file"

The build phase can't find the spec. Regenerate the plan:

uv run adw_plan.py <issue>
# This creates specs/issue-<n>-adw-<id>-*.md
# Then run build with the new ADW ID

Build failed mid-phase

Resume from the failed phase using the existing ADW ID:

# Find the ADW ID
ls agents/
cat agents/<adw-id>/adw_state.json

# Resume the specific phase
uv run adw_build.py <issue> <adw-id>
uv run adw_test.py <issue> <adw-id>
uv run adw_review.py <issue> <adw-id>

Tests failing, auto-fix not working

The test auto-fix loop runs 3 times before giving up. Check what it attempted:

cat agents/<adw-id>/tester/raw_output.jsonl | python3 -m json.tool

Common causes:

• Missing test dependencies in package.json
• Test requires a running server that isn't started
• Test requires database state that doesn't exist
• E2E tests require a specific browser setup

Git Issues

"Branch already exists"

git branch -d feat-<n>-<adw-id>-<slug>   # Delete local
git push origin --delete feat-<n>-<adw-id>-<slug>   # Delete remote

"Merge conflict in specs/"

Specs are generated files. If two ADW runs both added a spec file with the same name, keep both and rename one.

ADW is committing to the wrong branch

Check the state file:

cat agents/<adw-id>/adw_state.json | python3 -m json.tool
# Look at "branch_name"

Webhook Issues

Webhook not receiving events

1. Check that the server is running: GET https://your-domain.com/health
2. Check GitHub webhook delivery logs: repo → Settings → Webhooks → your webhook → Recent Deliveries
3. Verify the webhook secret matches GITHUB_WEBHOOK_SECRET
4. Check ngrok/Cloudflare tunnel is active

Webhook fires but no ADW starts

# Check the webhook server logs
uv run adw_triggers/trigger_webhook.py  # run in foreground to see logs

Look for:

• "No trigger keyword found" — issue comment doesn't contain a trigger keyword
• "Already processing issue" — another ADW is running for this issue
• Auth errors

Cron trigger not picking up issues

# Run with verbose logging
uv run adw_triggers/trigger_cron.py

The cron picks up issues where:

• Issue is open with zero comments, OR
• Latest comment is exactly adw

Leading/trailing spaces in the comment prevent the trigger. Ensure the comment is exactly adw.

Hook Issues

Hook not firing

1. Run /hooks in Claude Code to verify registration
2. Check JSON syntax in settings.json
3. Verify the script is executable: chmod +x .claude/hooks/my-hook.py
4. Check the matcher pattern — it's case-sensitive
5. Enable debug: claude --debug

Hook running but not blocking

Exit code 2 blocks and shows stderr to Claude. Exit code 0 does NOT show stdout to Claude (except UserPromptSubmit). Check your exit code logic.

"Hook command not found"

Use absolute paths in hook commands:

{
  "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/my-hook.py"
}

$CLAUDE_PROJECT_DIR is the absolute path to the project root directory.

API Rate Limits

If you're hitting Anthropic API rate limits during parallel runs:

1. Reduce parallelism — run 2-3 issues at a time instead of 10
2. Add delays between parallel starts
3. Use Sonnet instead of Opus (higher rate limits)

Monitor usage at console.anthropic.com.