{
  "id": "page:docs-user-guide-reference-troubleshooting",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/reference/troubleshooting.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/reference/troubleshooting.md",
    "sourceKind": "repo-docs",
    "title": "Troubleshooting Guide",
    "displayName": "Troubleshooting Guide",
    "slug": "docs/user-guide/reference/troubleshooting",
    "articlePath": "wiki/docs/user-guide/reference/troubleshooting.md",
    "article": "\n# Troubleshooting Guide\n\n**Version:** 1.0\n**Last Updated:** 2026-01-25\n**Category:** Reference\n\nThis guide provides systematic troubleshooting procedures for common Babysitter issues. Each section includes symptoms, diagnosis steps, solutions, and prevention tips.\n\n---\n\n## Table of Contents\n\n- [Installation Issues](#installation-issues)\n- [Plugin Issues](#plugin-issues)\n- [Run Execution Issues](#run-execution-issues)\n- [Quality Convergence Issues](#quality-convergence-issues)\n- [Resumption Issues](#resumption-issues)\n- [Performance Issues](#performance-issues)\n- [Journal and State Issues](#journal-and-state-issues)\n- [Diagnostic Commands Reference](#diagnostic-commands-reference)\n- [When to Contact Support](#when-to-contact-support)\n\n---\n\n## Installation Issues\n\n### Node.js Not Found\n\n**Symptoms:**\n```\ncommand not found: npm\ncommand not found: node\n```\n\n**Diagnosis:**\n```bash\nwhich node\nwhich npm\nnode --version\n```\n\n**Solutions:**\n\n1. **Install Node.js via nvm (recommended):**\n   ```bash\n   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash\n   source ~/.bashrc  # or ~/.zshrc\n   nvm install 22\n   nvm use 22\n   ```\n\n2. **Direct installation:**\n   - Download from [nodejs.org](https://nodejs.org/)\n   - Install the LTS version (22.x)\n\n3. **Verify PATH:**\n   ```bash\n   echo $PATH | grep -E \"(node|npm)\"\n   ```\n\n**Prevention:** Use nvm to manage Node.js versions.\n\n---\n\n### Permission Denied During npm Install\n\n**Symptoms:**\n```\nnpm ERR! EACCES: permission denied, mkdir '/usr/local/lib/node_modules'\n```\n\n**Diagnosis:**\n```bash\nnpm config get prefix\nls -la $(npm config get prefix)/lib/node_modules/\n```\n\n**Solutions:**\n\n1. **Fix npm permissions (recommended):**\n   ```bash\n   mkdir ~/.npm-global\n   npm config set prefix '~/.npm-global'\n   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc\n   source ~/.zshrc\n   ```\n\n2. **Reinstall packages:**\n   ```bash\n   npm install -g @a5c-ai/babysitter@latest\n   ```\n\n**Prevention:** Never use `sudo npm install -g`. Configure npm for user installs.\n\n---\n\n### Core CLI or SDK Module Not Found\n\n**Symptoms:**\n```\nError: Cannot find module '@a5c-ai/babysitter-sdk'\n```\n\n**Diagnosis:**\n```bash\nnpm list -g @a5c-ai/babysitter-sdk\nwhich babysitter\necho $PATH\n```\n\n**Solutions:**\n\n1. **Install the main CLI globally:**\n   ```bash\n   npm install -g @a5c-ai/babysitter@latest\n   ```\n\n2. **Use npx (always works for the main CLI):**\n   ```bash\n   npx -y @a5c-ai/babysitter@latest --version\n   ```\n\n3. **If your code imports the SDK, install it in the project too:**\n   ```bash\n   npm install @a5c-ai/babysitter-sdk\n   ```\n\n4. **Check PATH includes npm global bin:**\n   ```bash\n   npm bin -g\n   # Add this to your PATH if not included\n   ```\n\n**Prevention:** Verify installation with `npm list -g` after installing.\n\n---\n\n### Version Mismatch Errors\n\n**Symptoms:**\n```\nError: Incompatible version: sdk@4.x requires babysitter@^4.x\n```\n\n**Diagnosis:**\n```bash\nnpm list -g @a5c-ai/babysitter-sdk\n```\n\n**Solutions:**\n\nUpdate all packages to the latest versions:\n```bash\nnpm install -g @a5c-ai/babysitter@latest @a5c-ai/babysitter-agent@latest\n```\n\n**Prevention:** Update all packages together, not individually.\n\n---\n\n### jq Not Found\n\n**Symptoms:**\n```\ncommand not found: jq\njq: command not found\n```\n\nMany Babysitter diagnostic commands use `jq` for JSON processing. Without it, commands like journal analysis and status inspection will fail.\n\n**Diagnosis:**\n```bash\nwhich jq\njq --version\n```\n\n**Solutions:**\n\nInstall `jq` for your platform:\n\n```bash\n# macOS\nbrew install jq\n\n# Ubuntu/Debian\nsudo apt-get install jq\n\n# Fedora/RHEL/CentOS\nsudo dnf install jq\n\n# Arch Linux\nsudo pacman -S jq\n\n# Windows (Chocolatey)\nchoco install jq\n\n# Windows (Scoop)\nscoop install jq\n\n# Windows (WSL) - use Ubuntu instructions\nsudo apt-get install jq\n```\n\n**Verify installation:**\n```bash\njq --version\n# Expected: jq-1.6 or higher\n```\n\n**Prevention:** Install `jq` as part of your initial setup. It's a standard tool for working with JSON on the command line.\n\n---\n\n## Plugin Issues\n\n### Plugin Not Appearing in /skills\n\n**Symptoms:**\n- `/skills` command doesn't show \"babysit\"\n- \"Skill not found: babysit\" error\n\n**Diagnosis:**\n```bash\nclaude plugin list\nclaude plugin list | grep babysitter\n```\n\n**Step-by-Step Solution:**\n\n1. **Add marketplace (if not added):**\n   ```bash\n   claude plugin marketplace add a5c-ai/babysitter-claude\n   ```\n\n2. **Install plugin:**\n   ```bash\n   claude plugin install --scope user babysitter@a5c.ai\n   ```\n\n3. **Enable plugin:**\n   ```bash\n   claude plugin enable --scope user babysitter@a5c.ai\n   ```\n\n4. **Restart Claude Code completely:**\n   - Close all Claude Code windows\n   - Wait a few seconds\n   - Reopen Claude Code\n\n5. **Verify:**\n   ```bash\n   /skills\n   # Should show \"babysit\"\n   ```\n\n---\n\n### Plugin Install Fails\n\n**Symptoms:**\n```\nError: Plugin 'babysitter@a5c.ai' not found\n```\n\n**Diagnosis:**\n```bash\nclaude plugin marketplace list\n```\n\n**Solutions:**\n\n1. **Add marketplace first:**\n   ```bash\n   claude plugin marketplace add a5c-ai/babysitter-claude\n   ```\n\n2. **Check network connectivity:**\n   ```bash\n   curl -I https://github.com/a5c-ai/babysitter\n   ```\n\n3. **Try updating marketplace:**\n   ```bash\n   claude plugin marketplace update a5c.ai\n   ```\n\n---\n\n### Plugin Conflicts\n\n**Symptoms:**\n- Claude Code behaves unexpectedly\n- Other plugins stop working after Babysitter install\n\n**Diagnosis:**\n```bash\nclaude plugin list --all\n```\n\n**Solutions:**\n\n1. **Disable and re-enable:**\n   ```bash\n   claude plugin disable babysitter@a5c.ai\n   claude plugin enable babysitter@a5c.ai\n   ```\n\n2. **Check for conflicts:**\n   - Temporarily disable other plugins\n   - Test Babysitter alone\n   - Re-enable plugins one by one\n\n---\n\n## Run Execution Issues\n\n### Run Encountered an Error\n\n**Symptoms:**\n```\nError: Run encountered an error\n  at processIteration (process.js:123)\n```\n\n**Diagnosis:**\n```bash\n# Check journal for error details\nbabysitter run:events <runId> --filter-type RUN_FAILED --json\n\n# View last events\nbabysitter run:events <runId> --limit 10 --reverse --json\n```\n\n**Solutions:**\n\n1. **Identify the cause:**\n   ```bash\n   jq '.data.error' .a5c/runs/<runId>/journal/$(ls -t .a5c/runs/<runId>/journal/ | head -1)\n   ```\n\n2. **If journal conflict:**\n   - Ensure no other sessions are running the same workflow\n   - Delete state cache and rebuild:\n     ```bash\n     rm .a5c/runs/<runId>/state/state.json\n     babysitter run:status <runId>\n     ```\n\n3. **If task failure:**\n   - Fix the underlying issue (missing deps, file not found, etc.)\n   - Resume:\n     ```bash\n     /babysitter:call resume --run-id <runId>\n     ```\n\n4. **Ask Claude to analyze:**\n   ```\n   Analyze the babysitter run error for <runId> and try to recover\n   ```\n\n---\n\n### Task Execution Failed: ENOENT\n\n**Symptoms:**\n```\nTask failed: test-task-001\nError: ENOENT: no such file or directory\n```\n\n**Diagnosis:**\n```bash\n# Check task details\ncat .a5c/runs/<runId>/tasks/<effectId>/task.json | jq .\n\n# Check working directory\npwd\nls -la\n```\n\n**Solutions:**\n\n1. **Verify file paths:**\n   - Check if referenced files exist\n   - Ensure paths are correct for your system\n\n2. **Install dependencies:**\n   ```bash\n   npm install\n   ```\n\n3. **Check working directory:**\n   - Tasks run relative to the run directory\n   - Verify paths in task definition\n\n---\n\n### Agent Task Timeout\n\n**Symptoms:**\n```\nTask timeout: agent-task-001\nExecution exceeded 120s\n```\n\n**Diagnosis:**\n```bash\n# Check task that timed out\ncat .a5c/runs/<runId>/tasks/<effectId>/task.json | jq .\n```\n\n**Solutions:**\n\n1. **Reduce task scope:**\n   - Analyze specific files instead of entire codebase\n   - Break large tasks into smaller ones\n\n2. **Increase timeout (if necessary):**\n   ```javascript\n   await ctx.task(analyzeTask, { /* args */ }, {\n     timeout: 300000  // 5 minutes\n   });\n   ```\n\n3. **Check API status:**\n   - Verify Claude API is accessible\n   - Check for rate limiting\n\n---\n\n### Session Ended Unexpectedly\n\n**Symptoms:**\n```\nClaude Code session terminated\nRun ID: 01KFFTSF8TK8C9GT3YM9QYQ6WG\nStatus: interrupted\n```\n\n**Diagnosis:**\n```bash\nbabysitter run:status <runId> --json\n```\n\n**Solutions:**\n\nResume the run:\n```\n/babysitter:call resume --run-id 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\nBabysitter is designed to be resumable. All progress is preserved.\n\n---\n\n## Quality Convergence Issues\n\n### Quality Score Not Improving\n\n**Symptoms:**\n```\nIteration 1: Quality 65/100\nIteration 2: Quality 66/100\nIteration 3: Quality 65/100\n...\nIteration 5: Quality 66/100\nTarget not met: 85/100\n```\n\n**Diagnosis:**\n```bash\n# View effect resolutions\nbabysitter run:events <runId> --filter-type EFFECT_RESOLVED --json\n\n# Check recommendations\njq '.recommendations' .a5c/runs/<runId>/tasks/*/result.json\n```\n\n**Solutions:**\n\n1. **Review feedback:**\n   - Check what's blocking improvement\n   - Look for recurring issues\n\n2. **Lower target:**\n   ```\n   Use babysitter with 75% quality target\n   ```\n\n3. **Increase iterations:**\n   ```\n   Use babysitter with max 10 iterations\n   ```\n\n4. **Fix blocking issues:**\n   - Run tests manually: `npm test`\n   - Check lint: `npm run lint`\n   - Fix any consistent failures\n\n5. **Review scoring weights:**\n   - Some criteria may be weighted too heavily\n   - Adjust in process definition if needed\n\n---\n\n### Iterations Never Converge\n\n**Symptoms:**\n- Quality score oscillates without improvement\n- Maximum iterations reached without meeting target\n\n**Diagnosis:**\n```bash\n# Check quality trend\njq -s '[.[] | select(.type == \"EFFECT_RESOLVED\")] | map({effectId: .data.effectId, status: .data.status})' \\\n  .a5c/runs/<runId>/journal/*.json\n```\n\n**Solutions:**\n\n1. **Implement early exit on plateau:**\n   ```javascript\n   const recentScores = iterationResults.slice(-3).map(r => r.quality);\n   if (Math.max(...recentScores) - Math.min(...recentScores) < 2) {\n     ctx.log('Quality plateaued, stopping early');\n     break;\n   }\n   ```\n\n2. **Lower target to achievable level**\n\n3. **Review if target is realistic for the codebase**\n\n---\n\n### Inconsistent Quality Scores\n\n**Symptoms:**\n- Quality scores vary significantly between iterations\n- No clear trend\n\n**Diagnosis:**\n```bash\n# Check variance in scores\njq -s '[.[] | select(.type == \"EFFECT_RESOLVED\")] | length' \\\n  .a5c/runs/<runId>/journal/*.json\n```\n\n**Solutions:**\n\n1. **Use more deterministic scoring criteria**\n\n2. **Ensure tests are stable (no flaky tests)**\n\n3. **Review agent scoring prompts for consistency**\n\n4. **Use `ctx.now()` instead of `Date.now()` for timestamps**\n\n---\n\n## Resumption Issues\n\n### Cannot Resume Completed Run\n\n**Symptoms:**\n- Resume has no effect\n- Run state shows \"completed\"\n\n**Diagnosis:**\n```bash\nbabysitter run:status <runId> --json | jq '.state'\n```\n\n**Solutions:**\n\nA completed run cannot be resumed - it's already finished. Create a new run instead.\n\n---\n\n### State Corruption After Manual Edits\n\n**Symptoms:**\n- Run behaves unexpectedly\n- Events don't match expected behavior\n\n**Diagnosis:**\n```bash\n# Check journal integrity\njq empty .a5c/runs/<runId>/journal/*.json 2>&1\n```\n\n**Solutions:**\n\n1. **Never edit journal files manually**\n\n2. **If state cache corrupted:**\n   ```bash\n   rm .a5c/runs/<runId>/state/state.json\n   babysitter run:status <runId>  # Rebuilds state\n   ```\n\n3. **If journal corrupted:**\n   - May need to start a new run\n   - Backup journal first for analysis\n\n---\n\n### Missing Run Directory\n\n**Symptoms:**\n```\nError: Run not found: 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\n**Diagnosis:**\n```bash\nls -la .a5c/runs/ | grep <runId>\n```\n\n**Solutions:**\n\n- Run directory was deleted or never created\n- Create a new run instead\n- Check if you're in the correct working directory\n\n---\n\n## Performance Issues\n\n### Slow Iteration Execution\n\n**Symptoms:**\n- Each iteration takes several minutes\n- Tasks run sequentially when they could be parallel\n\n**Diagnosis:**\n```bash\n# Find slow tasks\njq -s '[.[] | select(.type == \"EFFECT_RESOLVED\")] | map({effectId: .data.effectId, duration: ((.data.finishedAt | fromdateiso8601) - (.data.startedAt | fromdateiso8601))}) | sort_by(.duration) | reverse | .[0:5]' \\\n  .a5c/runs/<runId>/journal/*.json\n```\n\n**Solutions:**\n\n1. **Use parallel execution:**\n   ```javascript\n   const [coverage, lint, security] = await ctx.parallel.all([\n     () => ctx.task(coverageTask, {}),\n     () => ctx.task(lintTask, {}),\n     () => ctx.task(securityTask, {})\n   ]);\n   ```\n\n2. **Reduce agent task scope**\n\n3. **Set lower iteration limits**\n\n4. **Cache research results between iterations**\n\n---\n\n### High Disk Usage\n\n**Symptoms:**\n- `.a5c/` directory growing large\n- Disk space warnings\n\n**Diagnosis:**\n```bash\ndu -sh .a5c/\ndu -h .a5c/runs/* | sort -h | tail -10\n```\n\n**Solutions:**\n\n1. **Clean old runs:**\n   ```bash\n   # List runs by size\n   du -h .a5c/runs/* | sort -h\n\n   # Delete old runs\n   rm -rf .a5c/runs/<old-run-id>\n   ```\n\n2. **Archive completed runs:**\n   ```bash\n   tar -czf run-archive.tar.gz .a5c/runs/<runId>\n   rm -rf .a5c/runs/<runId>\n   ```\n\n3. **Add cleanup to workflow:**\n   - Periodically clean old runs\n   - Set up automated cleanup\n\n---\n\n### Memory Issues\n\n**Symptoms:**\n```\nFATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory\n```\n\n**Solutions:**\n\n1. **Increase Node.js memory:**\n   ```bash\n   export NODE_OPTIONS=\"--max-old-space-size=4096\"\n   ```\n\n2. **Reduce concurrent tasks**\n\n3. **Process smaller batches of files**\n\n---\n\n## Journal and State Issues\n\n### Journal Conflict\n\n**Symptoms:**\n```\nError: Journal conflict detected\n```\n\n**Diagnosis:**\n```bash\n# Check if multiple processes running\nps aux | grep babysitter\n```\n\n**Solutions:**\n\n1. **Ensure single writer:**\n   - Only one session should run a workflow at a time\n\n2. **Wait and retry:**\n   - If previous session crashed, wait a moment\n   - Resume the run\n\n3. **Rebuild state:**\n   ```bash\n   rm .a5c/runs/<runId>/state/state.json\n   babysitter run:status <runId>\n   ```\n\n---\n\n### Events Out of Order\n\n**Symptoms:**\n- Events appear in unexpected order\n- State doesn't match expectations\n\n**Diagnosis:**\n```bash\n# Check sequence numbers\njq '.seq' .a5c/runs/<runId>/journal/*.json | sort -n\n```\n\n**Solutions:**\n\n- Always use CLI or sort by `seq` field:\n  ```bash\n  jq -s 'sort_by(.seq)' .a5c/runs/<runId>/journal/*.json\n  ```\n\n- File system listing may not be sorted correctly\n\n---\n\n### State Cache Missing\n\n**Symptoms:**\n- CLI commands are slow on first access\n- State needs rebuilding\n\n**Diagnosis:**\n```bash\nls .a5c/runs/<runId>/state/\n```\n\n**Solutions:**\n\nThis is normal. The state cache is derived from the journal:\n\n```bash\n# Trigger rebuild\nbabysitter run:status <runId>\n```\n\nThe cache will be created automatically.\n\n---\n\n## Diagnostic Commands Reference\n\n### Run Status and Events\n\n```bash\n# Check run status\nbabysitter run:status <runId> --json\n\n# View all events\nbabysitter run:events <runId> --json\n\n# View last N events\nbabysitter run:events <runId> --limit 10 --reverse --json\n\n# Filter by event type\nbabysitter run:events <runId> --filter-type EFFECT_RESOLVED --json\n\n# Find failures\nbabysitter run:events <runId> --filter-type RUN_FAILED --json\n```\n\n### Task Information\n\n```bash\n# List pending tasks\nbabysitter task:list <runId> --pending --json\n\n# View task details\ncat .a5c/runs/<runId>/tasks/<effectId>/task.json | jq .\n\n# View task result\ncat .a5c/runs/<runId>/tasks/<effectId>/result.json | jq .\n```\n\n### System Checks\n\n```bash\n# Check core CLI version\nbabysitter --version\n\n# Check installed packages\nnpm list -g @a5c-ai/babysitter @a5c-ai/babysitter-agent\n\n# Check plugin status\nclaude plugin list | grep babysitter\n```\n\n### Journal Analysis\n\n```bash\n# Count events by type\njq -s 'group_by(.type) | map({type: .[0].type, count: length})' \\\n  .a5c/runs/<runId>/journal/*.json\n\n# Find failed tasks\njq 'select(.type == \"EFFECT_RESOLVED\" and .data.status == \"error\")' \\\n  .a5c/runs/<runId>/journal/*.json\n\n# Check effect resolutions\njq 'select(.type == \"EFFECT_RESOLVED\") | {effectId: .data.effectId, status: .data.status}' \\\n  .a5c/runs/<runId>/journal/*.json\n```\n\n---\n\n## When to Contact Support\n\nContact support if you experience:\n\n1. **Persistent crashes** that cannot be resolved with troubleshooting\n2. **Data corruption** that affects the journal or state\n3. **Security concerns** about the tool behavior\n4. **Bugs** that are reproducible with clear steps\n\n### How to Report Issues\n\n1. **Gather information:**\n   - OS and version\n   - Node.js version: `node --version`\n   - Claude Code version: `claude --version`\n   - Babysitter CLI version: `babysitter --version`\n   - Full error message and stack trace\n   - Steps to reproduce\n\n2. **Include diagnostic output:**\n   ```bash\n   babysitter run:status <runId> --json > diagnostic.json\n   babysitter run:events <runId> --limit 50 --reverse --json >> diagnostic.json\n   ```\n\n3. **Create issue at:**\n   [GitHub Issues](https://github.com/a5c-ai/babysitter/issues)\n\n4. **For discussions:**\n   [GitHub Discussions](https://github.com/a5c-ai/babysitter/discussions)\n\n---\n\n## Related Documentation\n\n- [FAQ](./faq.md) - Common questions answered\n- [Error Catalog](./error-catalog.md) - Error messages explained\n- [Installation Guide](../getting-started/installation.md) - Setup instructions\n- [Run Resumption](../features/run-resumption.md) - Recovery procedures\n\n---\n\n**Document Status:** Complete\n**Last Updated:** 2026-01-25\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}