{
  "id": "page:docs-user-guide-reference-error-catalog",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/reference/error-catalog.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/reference/error-catalog.md",
    "sourceKind": "repo-docs",
    "title": "Error Catalog",
    "displayName": "Error Catalog",
    "slug": "docs/user-guide/reference/error-catalog",
    "articlePath": "wiki/docs/user-guide/reference/error-catalog.md",
    "article": "\n# Error Catalog\n\n**Version:** 1.0\n**Last Updated:** 2026-01-25\n**Category:** Reference\n\nThis catalog provides comprehensive documentation of Babysitter error messages, their meanings, causes, and solutions.\n\n---\n\n## Table of Contents\n\n- [Installation Errors](#installation-errors)\n- [Plugin Errors](#plugin-errors)\n- [Run Execution Errors](#run-execution-errors)\n- [Task Execution Errors](#task-execution-errors)\n- [Quality and Scoring Errors](#quality-and-scoring-errors)\n- [Journal and State Errors](#journal-and-state-errors)\n- [Network and API Errors](#network-and-api-errors)\n- [File System Errors](#file-system-errors)\n- [Error Codes Reference](#error-codes-reference)\n\n---\n\n## Installation Errors\n\n### ERR_MODULE_NOT_FOUND\n\n```\nError: Cannot find module '@a5c-ai/babysitter-sdk'\n```\n\n**Meaning:** The Babysitter SDK package is not installed or not accessible to the current project.\n\n**Causes:**\n- SDK not installed globally\n- npm global path not in system PATH\n- Wrong Node.js version active\n\n**Solutions:**\n1. Install globally:\n   ```bash\n   npm install -g @a5c-ai/babysitter@latest\n   ```\n2. Use npx:\n   ```bash\n   npx -y @a5c-ai/babysitter@latest --version\n   ```\n3. If your process code imports the SDK, install it in the project:\n   ```bash\n   npm install @a5c-ai/babysitter-sdk\n   ```\n4. Check PATH includes npm global bin:\n   ```bash\n   npm bin -g\n   # Add to PATH if needed\n   ```\n\n---\n\n### EACCES: permission denied\n\n```\nnpm ERR! EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...'\n```\n\n**Meaning:** npm doesn't have permission to write to the global packages directory.\n\n**Causes:**\n- npm configured to use system directory\n- Insufficient permissions\n- Previous sudo install\n\n**Solutions:**\n1. Configure npm for user installs:\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   ```\n2. Retry installation:\n   ```bash\n   npm install -g @a5c-ai/babysitter@latest\n   ```\n\n---\n\n### ERESOLVE: unable to resolve dependency tree\n\n```\nnpm ERR! ERESOLVE unable to resolve dependency tree\nnpm ERR! Could not resolve dependency: @a5c-ai/babysitter-sdk@^4.0.0\n```\n\n**Meaning:** Version conflicts between Babysitter packages.\n\n**Causes:**\n- Mixed versions of packages\n- Outdated package in cache\n- Conflicting peer dependencies\n\n**Solutions:**\n1. Update all packages together:\n   ```bash\n   npm install -g @a5c-ai/babysitter@latest @a5c-ai/babysitter-agent@latest\n   ```\n2. Clear npm cache if needed:\n   ```bash\n   npm cache clean --force\n   ```\n\n---\n\n## Plugin Errors\n\n### Plugin not found: babysitter@a5c.ai\n\n```\nError: Plugin 'babysitter@a5c.ai' not found\nAvailable plugins: [...]\n```\n\n**Meaning:** The Babysitter plugin is not installed in Claude Code.\n\n**Causes:**\n- Plugin not installed\n- Marketplace not added\n- Plugin disabled\n\n**Solutions:**\n1. Add marketplace:\n   ```bash\n   claude plugin marketplace add a5c-ai/babysitter-claude\n   ```\n2. Install plugin:\n   ```bash\n   claude plugin install --scope user babysitter@a5c.ai\n   ```\n3. Enable plugin:\n   ```bash\n   claude plugin enable --scope user babysitter@a5c.ai\n   ```\n4. Restart Claude Code\n\n---\n\n### Skill not found: babysit\n\n```\nError: Skill 'babysit' not found\n```\n\n**Meaning:** The babysit skill is not available in the current session.\n\n**Causes:**\n- Plugin not enabled\n- Claude Code not restarted after plugin install\n- Plugin load error\n\n**Solutions:**\n1. Check plugin status:\n   ```bash\n   claude plugin list | grep babysitter\n   ```\n2. Enable if disabled:\n   ```bash\n   claude plugin enable --scope user babysitter@a5c.ai\n   ```\n3. Restart Claude Code completely\n4. Verify with `/skills`\n\n---\n\n### Plugin load error\n\n```\nError loading plugin babysitter@a5c.ai: [details]\n```\n\n**Meaning:** The plugin failed to initialize.\n\n**Causes:**\n- Corrupted plugin files\n- Version incompatibility\n- Missing dependencies\n\n**Solutions:**\n1. Reinstall plugin:\n   ```bash\n   claude plugin uninstall babysitter@a5c.ai\n   claude plugin install --scope user babysitter@a5c.ai\n   ```\n2. Update marketplace:\n   ```bash\n   claude plugin marketplace update a5c.ai\n   ```\n3. Check for updates:\n   ```bash\n   claude plugin update babysitter@a5c.ai\n   ```\n\n---\n\n## Run Execution Errors\n\n### Run encountered an error\n\n```\nError: Run encountered an error\n  at processIteration (process.js:123)\n  Caused by: [underlying error]\n```\n\n**Meaning:** The run failed during execution.\n\n**Causes:**\n- Task failure\n- Journal conflict\n- Process definition error\n- External dependency failure\n\n**Solutions:**\n1. Check journal for details:\n   ```\n   What error caused my babysitter run to fail?\n   ```\n2. Fix underlying issue\n3. Resume if possible:\n   ```\n   /babysitter:call resume\n   ```\n\n---\n\n### Run not found\n\n```\nError: Run not found: 01KFFTSF8TK8C9GT3YM9QYQ6WG\n```\n\n**Meaning:** The specified run ID doesn't exist.\n\n**Causes:**\n- Run was deleted\n- Wrong run ID\n- Wrong working directory\n- Run never created\n\n**Solutions:**\n1. Ask Claude to find available runs:\n   ```\n   What babysitter runs have I done recently?\n   ```\n2. Check working directory\n3. Use correct run ID\n\n---\n\n### Run already completed\n\n```\nError: Cannot resume completed run\nRun state: completed\n```\n\n**Meaning:** Attempting to resume a run that has already finished.\n\n**Causes:**\n- Run finished successfully\n- Trying to resume wrong run\n\n**Solutions:**\n- Completed runs cannot be resumed\n- Create a new run for additional work\n\n---\n\n### Run is already being executed\n\n```\nError: Run is already being executed by another session\n```\n\n**Meaning:** Another session is actively running this workflow.\n\n**Causes:**\n- Multiple Claude Code windows running same workflow\n- Previous session didn't terminate cleanly\n\n**Solutions:**\n1. Wait for other session to complete\n2. Close other Claude Code sessions\n3. Wait a moment and retry (for stale locks)\n\n---\n\n## Task Execution Errors\n\n### ENOENT: no such file or directory\n\n```\nError: ENOENT: no such file or directory, open '/path/to/file.js'\nTask failed: task-001\n```\n\n**Meaning:** A task tried to access a file that doesn't exist.\n\n**Causes:**\n- Incorrect file path in task definition\n- File deleted or moved\n- Path resolution issue\n- Dependencies not installed\n\n**Solutions:**\n1. Verify file exists:\n   ```bash\n   ls -la /path/to/file.js\n   ```\n2. Check paths in task definition\n3. Install missing dependencies:\n   ```bash\n   npm install\n   ```\n\n---\n\n### Task timeout\n\n```\nError: Task timeout: agent-task-001\nExecution exceeded 120s\n```\n\n**Meaning:** A task took too long to complete.\n\n**Causes:**\n- Large context for agent task\n- API latency\n- Complex computation\n- Network issues\n\n**Solutions:**\n1. Reduce task scope\n2. Increase timeout:\n   ```javascript\n   await ctx.task(task, args, { timeout: 300000 });\n   ```\n3. Check API status\n4. Split into smaller tasks\n\n---\n\n### Task failed with exit code\n\n```\nError: Task failed with exit code 1\nCommand: npm test\nstderr: [error output]\n```\n\n**Meaning:** A shell/node task command failed.\n\n**Causes:**\n- Test failures\n- Build errors\n- Missing dependencies\n- Script errors\n\n**Solutions:**\n1. Check stderr for details\n2. Run command manually to debug:\n   ```bash\n   npm test\n   ```\n3. Fix underlying issues\n4. Resume run\n\n---\n\n### Agent task error\n\n```\nError: Agent task failed\n  Caused by: API rate limit exceeded\n```\n\n**Meaning:** The LLM API call failed.\n\n**Causes:**\n- Rate limiting\n- API outage\n- Invalid request\n- Token limit exceeded\n\n**Solutions:**\n1. Wait and retry (for rate limits)\n2. Check API status\n3. Reduce context size\n4. Resume run after waiting\n\n---\n\n## Quality and Scoring Errors\n\n### Quality target not met\n\n```\nQuality target not met after 5 iterations\nFinal score: 78/100\nTarget: 85/100\n```\n\n**Meaning:** The quality convergence loop couldn't reach the target score.\n\n**Causes:**\n- Unrealistic target\n- Fundamental code issues\n- Scoring criteria too strict\n- Not enough iterations\n\n**Solutions:**\n1. Lower quality target:\n   ```\n   Use babysitter with 75% quality target\n   ```\n2. Increase iterations:\n   ```\n   Use babysitter with max 10 iterations\n   ```\n3. Review and fix blocking issues\n4. Adjust scoring weights\n\n---\n\n### Quality score validation error\n\n```\nError: Invalid quality score returned by agent\nExpected: number between 0-100\nReceived: [invalid value]\n```\n\n**Meaning:** The scoring agent returned an invalid score.\n\n**Causes:**\n- Agent prompt issue\n- Response parsing error\n- Schema mismatch\n\n**Solutions:**\n1. Check agent task definition\n2. Verify output schema\n3. Review agent prompt for clarity\n\n---\n\n## Journal and State Errors\n\n### Journal conflict detected\n\n```\nError: Journal conflict detected\nMultiple writes attempted at sequence 42\n```\n\n**Meaning:** Concurrent writes to the journal were detected.\n\n**Causes:**\n- Multiple sessions running same workflow\n- Race condition\n- Stale lock\n\n**Solutions:**\n1. Ensure single session per run\n2. Close other Claude Code windows\n3. Wait and retry\n4. Delete state cache and rebuild:\n   ```bash\n   rm .a5c/runs/<runId>/state/state.json\n   babysitter run:status <runId>\n   ```\n\n---\n\n### Journal integrity error\n\n```\nError: Journal integrity check failed\nEvent 43 has invalid sequence\n```\n\n**Meaning:** The journal has inconsistent or corrupted data.\n\n**Causes:**\n- Manual journal editing\n- Disk write failure\n- Interrupted write\n- File corruption\n\n**Solutions:**\n1. Check journal files:\n   ```bash\n   jq empty .a5c/runs/<runId>/journal/*.json\n   ```\n2. If corrupted, may need to start new run\n3. Backup and investigate:\n   ```bash\n   cp -r .a5c/runs/<runId> backup-run\n   ```\n\n---\n\n### State reconstruction failed\n\n```\nError: Failed to reconstruct state from journal\nInvalid event at sequence 15\n```\n\n**Meaning:** The state cache couldn't be rebuilt from journal events.\n\n**Causes:**\n- Corrupted journal\n- Missing events\n- Invalid event format\n\n**Solutions:**\n1. Delete state cache:\n   ```bash\n   rm .a5c/runs/<runId>/state/state.json\n   ```\n2. Check journal integrity\n3. May need to start new run if journal corrupted\n\n---\n\n## Network and API Errors\n\n### ETIMEDOUT\n\n```\nError: connect ETIMEDOUT 104.26.0.100:443\n```\n\n**Meaning:** Network connection timed out.\n\n**Causes:**\n- Network issues\n- Firewall blocking\n- Service unavailable\n- DNS issues\n\n**Solutions:**\n1. Check internet connectivity\n2. Verify service is accessible\n3. Check firewall settings\n4. Retry after network recovery\n\n---\n\n### API rate limit exceeded\n\n```\nError: API rate limit exceeded\nRetry after: 60 seconds\n```\n\n**Meaning:** Too many API requests in a short period.\n\n**Causes:**\n- High-frequency requests\n- Concurrent tasks making requests\n- Account rate limits\n\n**Solutions:**\n1. Wait and retry\n2. Reduce parallel API calls\n3. Add delays between requests\n4. Check account rate limits\n\n---\n\n### SSL/TLS error\n\n```\nError: unable to verify the first certificate\n```\n\n**Meaning:** SSL certificate verification failed.\n\n**Causes:**\n- Certificate issues\n- Proxy interference\n- Outdated certificates\n\n**Solutions:**\n1. Check system time is correct\n2. Update CA certificates\n3. Check proxy settings\n4. Don't disable SSL verification (security risk)\n\n---\n\n## File System Errors\n\n### ENOSPC: no space left on device\n\n```\nError: ENOSPC: no space left on device\n```\n\n**Meaning:** Disk is full.\n\n**Causes:**\n- Many large runs\n- Large artifacts\n- System disk full\n\n**Solutions:**\n1. Clean old runs:\n   ```bash\n   rm -rf .a5c/runs/<old-run-id>\n   ```\n2. Check disk space:\n   ```bash\n   df -h\n   ```\n3. Free space on disk\n\n---\n\n### EPERM: operation not permitted\n\n```\nError: EPERM: operation not permitted, open '/path/to/file'\n```\n\n**Meaning:** Insufficient permissions for file operation.\n\n**Causes:**\n- File permissions\n- Read-only file system\n- File locked by another process\n\n**Solutions:**\n1. Check file permissions:\n   ```bash\n   ls -la /path/to/file\n   ```\n2. Fix permissions if needed\n3. Check for file locks\n\n---\n\n### EMFILE: too many open files\n\n```\nError: EMFILE: too many open files\n```\n\n**Meaning:** System file descriptor limit reached.\n\n**Causes:**\n- Many concurrent file operations\n- System limit too low\n- File handles not closed\n\n**Solutions:**\n1. Increase ulimit:\n   ```bash\n   ulimit -n 4096\n   ```\n2. Close other applications\n3. Reduce concurrent operations\n\n---\n\n## Error Codes Reference\n\n### Quick Reference Table\n\n| Error Code | Category | Common Cause | Quick Fix |\n|------------|----------|--------------|-----------|\n| `ENOENT` | File System | File not found | Check paths |\n| `EACCES` | Permissions | No permission | Fix permissions |\n| `EADDRINUSE` | Network | Port in use | Kill process or change port |\n| `ECONNREFUSED` | Network | Service not running | Start service |\n| `ETIMEDOUT` | Network | Connection timeout | Check network |\n| `ENOSPC` | File System | Disk full | Free space |\n| `EPERM` | Permissions | Operation denied | Check permissions |\n| `EMFILE` | System | Too many files | Increase ulimit |\n| `ERR_MODULE_NOT_FOUND` | Node.js | Module missing | Install package |\n| `ERESOLVE` | npm | Dependency conflict | Update packages |\n\n### Exit Codes\n\n| Exit Code | Meaning | Action |\n|-----------|---------|--------|\n| 0 | Success | None needed |\n| 1 | General error | Check error message |\n| 2 | Command not found | Check installation |\n| 126 | Permission denied | Fix permissions |\n| 127 | Command not found | Check PATH |\n| 137 | Out of memory (SIGKILL) | Increase memory |\n| 143 | Terminated (SIGTERM) | Check what terminated |\n\n---\n\n## Related Documentation\n\n- [Troubleshooting Guide](./troubleshooting.md) - Step-by-step problem resolution\n- [FAQ](./faq.md) - Common questions answered\n- [Installation Guide](../getting-started/installation.md) - Setup help\n\n---\n\n## Reporting New Errors\n\nIf you encounter an error not listed here:\n\n1. **Document the error:**\n   - Full error message\n   - Stack trace (if available)\n   - Steps to reproduce\n\n2. **Gather diagnostics:**\n   ```bash\n   babysitter run:status <runId> --json > diagnostic.json\n   babysitter run:events <runId> --limit 20 --reverse --json >> diagnostic.json\n   ```\n\n3. **Report at:**\n   [GitHub Issues](https://github.com/a5c-ai/babysitter/issues)\n\n---\n\n**Document Status:** Complete\n**Last Updated:** 2026-01-25\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}