{
  "id": "page:docs-reference-error-codes",
  "_kind": "Page",
  "_file": "wiki/docs/reference/error-codes.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/reference/ERROR_CODES.md",
    "sourceKind": "repo-docs",
    "title": "Babysitter Plugin Error Codes",
    "displayName": "Babysitter Plugin Error Codes",
    "slug": "docs/reference/error-codes",
    "articlePath": "wiki/docs/reference/ERROR_CODES.md",
    "article": "\n# Babysitter Plugin Error Codes\n\nThis document defines the standardized error code system for the babysitter plugin.\n\n## Error Code Format\n\nAll error codes follow the format: `BSIT-XXXX`\n\n### Code Categories\n\n| Range | Category | Description |\n|-------|----------|-------------|\n| 1XXX | Installation/Setup | Errors related to installation, dependencies, and initial setup |\n| 2XXX | Configuration | Errors related to configuration files and settings |\n| 3XXX | Runtime/Execution | Errors that occur during task execution |\n| 4XXX | State/Journal | Errors related to state management and journal files |\n| 5XXX | Hook | Errors related to hook discovery and execution |\n| 9XXX | Unknown/Internal | Unexpected errors and internal failures |\n\n---\n\n## Installation/Setup Errors (1XXX)\n\n### BSIT-1001: Node.js Version Mismatch\n\n**Description:** The installed Node.js version does not meet the minimum requirements.\n\n**Common Causes:**\n- Node.js is outdated\n- Multiple Node.js versions installed with wrong one in PATH\n- nvm/fnm using an older version\n\n**Recovery Steps:**\n1. Check current version: `node --version`\n2. Install Node.js 18.x or later from https://nodejs.org\n3. If using nvm: `nvm install 18 && nvm use 18`\n4. Verify: `node --version`\n\n**Example Error Message:**\n```\n[BSIT-1001] Node.js version mismatch: found v16.20.0, required >=18.0.0\n```\n\n---\n\n### BSIT-1002: jq Not Found\n\n**Description:** The `jq` command-line JSON processor is not installed or not in PATH.\n\n**Common Causes:**\n- jq not installed on the system\n- jq installed but not in PATH\n- Conda/virtualenv environment missing jq\n\n**Recovery Steps:**\n1. Install jq:\n   - macOS: `brew install jq`\n   - Ubuntu/Debian: `sudo apt-get install jq`\n   - Windows: `choco install jq` or `winget install jqlang.jq`\n2. Verify installation: `jq --version`\n3. Ensure jq is in your PATH\n\n**Example Error Message:**\n```\n[BSIT-1002] Required dependency 'jq' not found. Install it with your package manager.\n```\n\n---\n\n### BSIT-1003: Plugin Not Installed\n\n**Description:** The babysitter plugin is not properly installed or registered with Claude Code.\n\n**Common Causes:**\n- Plugin directory missing or moved\n- Plugin not registered in Claude Code settings\n- Corrupted installation\n\n**Recovery Steps:**\n1. Verify plugin exists: `ls -la ~/.claude/plugins/babysitter`\n2. Re-register plugin: `claude plugins add babysitter`\n3. Restart Claude Code session\n4. Check plugin status: `claude plugins list`\n\n**Example Error Message:**\n```\n[BSIT-1003] Babysitter plugin not installed. Run 'claude plugins add babysitter' to install.\n```\n\n---\n\n### BSIT-1004: SDK CLI Not Found\n\n**Description:** The babysitter SDK CLI (`bsit` or `npx @a5c-ai/babysitter`) is not available.\n\n**Common Causes:**\n- SDK package not installed\n- npm global bin not in PATH\n- Package installation failed\n\n**Recovery Steps:**\n1. Install the SDK: `npm install -g @a5c-ai/babysitter`\n2. Or use npx: `npx @a5c-ai/babysitter --help`\n3. Verify PATH includes npm global bin: `npm bin -g`\n4. Add to PATH if needed\n\n**Example Error Message:**\n```\n[BSIT-1004] SDK CLI not found. Install with 'npm install -g @a5c-ai/babysitter'\n```\n\n---\n\n### BSIT-1005: Git Not Available\n\n**Description:** Git is not installed or not accessible in the current environment.\n\n**Common Causes:**\n- Git not installed\n- Git not in PATH\n- Restricted shell environment\n\n**Recovery Steps:**\n1. Install git from https://git-scm.com\n2. Verify: `git --version`\n3. Ensure git is in your PATH\n\n**Example Error Message:**\n```\n[BSIT-1005] Git is required but not found in PATH. Install git and try again.\n```\n\n---\n\n## Configuration Errors (2XXX)\n\n### BSIT-2001: Invalid Configuration\n\n**Description:** The configuration file contains invalid or malformed data.\n\n**Common Causes:**\n- Syntax error in JSON/YAML configuration\n- Invalid field values\n- Missing required fields\n- Unsupported configuration version\n\n**Recovery Steps:**\n1. Validate JSON syntax: `jq . .a5c/config.json`\n2. Check for required fields in documentation\n3. Reset to default: `bsit config reset`\n4. Re-run configuration wizard: `bsit configure`\n\n**Example Error Message:**\n```\n[BSIT-2001] Invalid configuration in .a5c/config.json: unexpected token at line 15\n```\n\n---\n\n### BSIT-2002: Missing Runs Directory\n\n**Description:** The `.a5c/runs` directory does not exist and cannot be created.\n\n**Common Causes:**\n- Directory was deleted\n- Permission issues\n- Disk full\n- Read-only filesystem\n\n**Recovery Steps:**\n1. Create manually: `mkdir -p .a5c/runs`\n2. Check permissions: `ls -la .a5c`\n3. Verify disk space: `df -h .`\n4. Check filesystem is writable\n\n**Example Error Message:**\n```\n[BSIT-2002] Runs directory not found and cannot be created: .a5c/runs\n```\n\n---\n\n### BSIT-2003: Invalid Log Level\n\n**Description:** The specified log level is not recognized.\n\n**Common Causes:**\n- Typo in log level value\n- Using unsupported log level name\n- Environment variable set incorrectly\n\n**Recovery Steps:**\n1. Use valid log levels: `debug`, `info`, `warn`, `error`, `silent`\n2. Check environment: `echo $BABYSITTER_LOG_LEVEL`\n3. Update configuration with valid level\n\n**Example Error Message:**\n```\n[BSIT-2003] Invalid log level 'verbose'. Valid levels: debug, info, warn, error, silent\n```\n\n---\n\n### BSIT-2004: Configuration File Not Found\n\n**Description:** The expected configuration file does not exist.\n\n**Common Causes:**\n- First run without initialization\n- Configuration file deleted\n- Wrong working directory\n\n**Recovery Steps:**\n1. Initialize configuration: `bsit init`\n2. Check working directory contains `.a5c` folder\n3. Create default config: `bsit config reset`\n\n**Example Error Message:**\n```\n[BSIT-2004] Configuration file not found: .a5c/config.json\n```\n\n---\n\n### BSIT-2005: Permission Denied\n\n**Description:** Cannot read or write to a required file or directory due to permissions.\n\n**Common Causes:**\n- File owned by different user\n- Restrictive directory permissions\n- SELinux/AppArmor restrictions\n- Windows file locks\n\n**Recovery Steps:**\n1. Check ownership: `ls -la <path>`\n2. Fix permissions: `chmod 755 <directory>` or `chmod 644 <file>`\n3. Check for file locks on Windows\n4. Run as appropriate user\n\n**Example Error Message:**\n```\n[BSIT-2005] Permission denied: cannot write to .a5c/runs/current/state.json\n```\n\n---\n\n## Runtime/Execution Errors (3XXX)\n\n### BSIT-3001: Process Not Found\n\n**Description:** The expected process file or definition could not be located.\n\n**Common Causes:**\n- Process name misspelled\n- Process file deleted or moved\n- Process not installed with plugin\n- Custom process not in search path\n\n**Recovery Steps:**\n1. List available processes: `bsit process list`\n2. Check process name spelling\n3. Verify process file exists in plugin/processes\n4. Add custom process path to configuration\n\n**Example Error Message:**\n```\n[BSIT-3001] Process not found: 'tdd-quality-convergence'. Run 'bsit process list' to see available processes.\n```\n\n---\n\n### BSIT-3002: Task Execution Failed\n\n**Description:** A task failed to execute successfully.\n\n**Common Causes:**\n- Task dependencies not met\n- External command failed\n- Timeout exceeded\n- Resource unavailable\n\n**Recovery Steps:**\n1. Check task logs: `bsit logs --run <run-id> --task <task-id>`\n2. Verify task dependencies are satisfied\n3. Increase timeout if needed\n4. Check external service availability\n5. Retry with: `bsit retry --task <task-id>`\n\n**Example Error Message:**\n```\n[BSIT-3002] Task execution failed: 'build-project' exited with code 1\n```\n\n---\n\n### BSIT-3003: Breakpoint Timeout\n\n**Description:** A breakpoint wait exceeded the maximum allowed time.\n\n**Common Causes:**\n- User did not respond to breakpoint prompt\n- Network issues with notification\n- Claude Code session disconnected\n- Timeout set too low\n\n**Recovery Steps:**\n1. Check for pending breakpoint notifications\n2. Resume manually: `bsit resume --run <run-id>`\n3. Increase timeout in configuration\n4. Check Claude Code session is active\n\n**Example Error Message:**\n```\n[BSIT-3003] Breakpoint timeout after 300s waiting for user input at 'pre-deploy-approval'\n```\n\n---\n\n### BSIT-3004: Run Already Active\n\n**Description:** Attempted to start a new run while another is already active.\n\n**Common Causes:**\n- Previous run not properly terminated\n- Concurrent babysitter invocations\n- Stale lock file\n\n**Recovery Steps:**\n1. Check active runs: `bsit status`\n2. Stop active run: `bsit stop --run <run-id>`\n3. Force stop if needed: `bsit stop --force`\n4. Remove stale lock: `rm .a5c/runs/.lock`\n\n**Example Error Message:**\n```\n[BSIT-3004] Run already active: run-2024-01-15-abc123. Stop it first with 'bsit stop'\n```\n\n---\n\n### BSIT-3005: Maximum Iterations Exceeded\n\n**Description:** The run exceeded the maximum number of allowed iterations.\n\n**Common Causes:**\n- Infinite loop in process logic\n- Convergence criteria not achievable\n- Max iterations set too low\n- Process design issue\n\n**Recovery Steps:**\n1. Review process logic for loops\n2. Check convergence criteria\n3. Increase max iterations if appropriate\n4. Analyze iteration logs for patterns\n\n**Example Error Message:**\n```\n[BSIT-3005] Maximum iterations (100) exceeded. Process may be in infinite loop.\n```\n\n---\n\n### BSIT-3006: Agent Communication Failed\n\n**Description:** Failed to communicate with the AI agent.\n\n**Common Causes:**\n- API rate limiting\n- Network connectivity issues\n- Invalid API credentials\n- Service outage\n\n**Recovery Steps:**\n1. Check network connectivity\n2. Verify API credentials\n3. Check for rate limiting\n4. Retry after waiting\n5. Check service status page\n\n**Example Error Message:**\n```\n[BSIT-3006] Agent communication failed: API returned 429 (rate limited). Retry after 60s.\n```\n\n---\n\n## State/Journal Errors (4XXX)\n\n### BSIT-4001: Journal Corrupted\n\n**Description:** The run journal file is corrupted or contains invalid data.\n\n**Common Causes:**\n- Interrupted write operation\n- Disk error\n- Manual editing introduced errors\n- Concurrent writes without locking\n\n**Recovery Steps:**\n1. Check journal file: `jq . .a5c/runs/<run-id>/journal.json`\n2. Restore from backup: `cp .a5c/runs/<run-id>/journal.json.bak .a5c/runs/<run-id>/journal.json`\n3. Recreate from state: `bsit repair --run <run-id>`\n4. Start fresh run if unrecoverable\n\n**Example Error Message:**\n```\n[BSIT-4001] Journal corrupted: .a5c/runs/run-abc123/journal.json - invalid JSON at offset 4521\n```\n\n---\n\n### BSIT-4002: State File Missing\n\n**Description:** A required state file is missing from the run directory.\n\n**Common Causes:**\n- File accidentally deleted\n- Incomplete run initialization\n- Storage failure\n- Cleanup ran prematurely\n\n**Recovery Steps:**\n1. Check run directory: `ls -la .a5c/runs/<run-id>/`\n2. Restore from backup if available\n3. Reinitialize state: `bsit init-state --run <run-id>`\n4. Start new run if state unrecoverable\n\n**Example Error Message:**\n```\n[BSIT-4002] State file missing: .a5c/runs/run-abc123/state/current.json\n```\n\n---\n\n### BSIT-4003: State File Invalid\n\n**Description:** The state file exists but contains invalid or inconsistent data.\n\n**Common Causes:**\n- Schema version mismatch\n- Incomplete state update\n- Manual editing errors\n- Serialization bug\n\n**Recovery Steps:**\n1. Validate state file: `bsit validate --run <run-id>`\n2. Compare with schema: Check state file against expected schema\n3. Reset to last checkpoint: `bsit rollback --run <run-id>`\n4. Repair state: `bsit repair --run <run-id>`\n\n**Example Error Message:**\n```\n[BSIT-4003] State file invalid: missing required field 'iteration' in state/current.json\n```\n\n---\n\n### BSIT-4004: Checkpoint Not Found\n\n**Description:** The requested checkpoint does not exist.\n\n**Common Causes:**\n- Checkpoint ID incorrect\n- Checkpoints not enabled\n- Checkpoint was cleaned up\n- No checkpoints created yet\n\n**Recovery Steps:**\n1. List checkpoints: `bsit checkpoints --run <run-id>`\n2. Verify checkpoint ID spelling\n3. Check checkpoint retention settings\n4. Create manual checkpoint: `bsit checkpoint create`\n\n**Example Error Message:**\n```\n[BSIT-4004] Checkpoint not found: checkpoint-5. Available: checkpoint-1, checkpoint-2, checkpoint-3\n```\n\n---\n\n### BSIT-4005: State Lock Acquisition Failed\n\n**Description:** Could not acquire lock on state files for writing.\n\n**Common Causes:**\n- Another process holds the lock\n- Stale lock file\n- Permission issues\n- Lock timeout too short\n\n**Recovery Steps:**\n1. Check for other babysitter processes: `ps aux | grep babysitter`\n2. Remove stale lock: `rm .a5c/runs/<run-id>/.lock`\n3. Wait and retry\n4. Increase lock timeout\n\n**Example Error Message:**\n```\n[BSIT-4005] State lock acquisition failed after 30s. Lock held by PID 12345.\n```\n\n---\n\n## Hook Errors (5XXX)\n\n### BSIT-5001: Hook Not Found\n\n**Description:** The specified hook file does not exist.\n\n**Common Causes:**\n- Hook file deleted\n- Wrong hook path in configuration\n- Hook type directory missing\n- Case sensitivity issues\n\n**Recovery Steps:**\n1. Check hook exists: `ls -la plugins/babysitter-unified/hooks/<hook-type>.sh`\n2. Verify hook path in configuration\n3. Create hook directory: `mkdir -p hooks/<hook-type>`\n4. Reinstall plugin if hooks missing\n\n**Example Error Message:**\n```\n[BSIT-5001] Hook not found: hooks/on-task-complete/custom-notify.sh\n```\n\n---\n\n### BSIT-5002: Hook Not Executable\n\n**Description:** The hook file exists but is not executable.\n\n**Common Causes:**\n- Missing execute permission\n- Wrong file type (not a script)\n- Windows permission issues\n- Git not preserving permissions\n\n**Recovery Steps:**\n1. Add execute permission: `chmod +x <hook-file>`\n2. On Windows, check file association\n3. Verify shebang line: First line should be `#!/bin/bash` or similar\n4. Git: `git update-index --chmod=+x <hook-file>`\n\n**Example Error Message:**\n```\n[BSIT-5002] Hook not executable: hooks/on-run-start/logger.sh. Run 'chmod +x' to fix.\n```\n\n---\n\n### BSIT-5003: Hook Execution Failed\n\n**Description:** The hook script exited with a non-zero status.\n\n**Common Causes:**\n- Script error (syntax or runtime)\n- Missing dependencies in hook\n- Environment variables not set\n- External service failure\n\n**Recovery Steps:**\n1. Run hook manually to see error: `bash -x <hook-file>`\n2. Check hook logs: `cat .a5c/runs/<run-id>/hooks.log`\n3. Verify hook dependencies\n4. Test hook in isolation\n\n**Example Error Message:**\n```\n[BSIT-5003] Hook execution failed: on-task-complete/metrics.sh exited with code 127 (command not found)\n```\n\n---\n\n### BSIT-5004: Hook Output Invalid\n\n**Description:** The hook produced output that could not be parsed or was invalid.\n\n**Common Causes:**\n- Hook output is not valid JSON (when JSON expected)\n- Output exceeds size limit\n- Encoding issues\n- Mixed stdout/stderr\n\n**Recovery Steps:**\n1. Test hook output: `<hook-file> | jq .`\n2. Ensure hook outputs only JSON to stdout\n3. Redirect debug output to stderr\n4. Check output encoding is UTF-8\n\n**Example Error Message:**\n```\n[BSIT-5004] Hook output invalid: on-breakpoint/cli.sh - expected JSON, got plain text\n```\n\n---\n\n### BSIT-5005: Hook Timeout\n\n**Description:** The hook execution exceeded the maximum allowed time.\n\n**Common Causes:**\n- Hook waiting for user input\n- Network request hanging\n- Infinite loop in hook\n- External service slow\n\n**Recovery Steps:**\n1. Review hook for blocking operations\n2. Add timeouts to external calls\n3. Increase hook timeout in configuration\n4. Make hook asynchronous if possible\n\n**Example Error Message:**\n```\n[BSIT-5005] Hook timeout: on-run-complete/notify.sh exceeded 30s limit\n```\n\n---\n\n## Unknown/Internal Errors (9XXX)\n\n### BSIT-9001: Unknown Error\n\n**Description:** An unexpected error occurred that doesn't match any known error pattern.\n\n**Common Causes:**\n- Unhandled exception\n- System-level failure\n- Memory/resource exhaustion\n- Bug in babysitter code\n\n**Recovery Steps:**\n1. Check full error logs: `bsit logs --verbose`\n2. Check system resources (disk, memory)\n3. Try restarting the operation\n4. Report bug with logs at https://github.com/a5c-ai/babysitter/issues\n\n**Example Error Message:**\n```\n[BSIT-9001] Unknown error occurred. See logs for details. Please report this issue.\n```\n\n---\n\n### BSIT-9002: Internal Error\n\n**Description:** An internal error occurred in the babysitter code.\n\n**Common Causes:**\n- Bug in babysitter code\n- Assertion failure\n- Invalid internal state\n- Race condition\n\n**Recovery Steps:**\n1. Save current state/logs for bug report\n2. Try operation again\n3. Update to latest babysitter version\n4. Report bug with reproduction steps\n\n**Example Error Message:**\n```\n[BSIT-9002] Internal error: assertion failed in StateManager.commit() - expected state to be initialized\n```\n\n---\n\n### BSIT-9003: Feature Not Implemented\n\n**Description:** The requested feature is not yet implemented.\n\n**Common Causes:**\n- Using development/preview feature\n- Feature planned for future release\n- Experimental flag not enabled\n\n**Recovery Steps:**\n1. Check documentation for feature availability\n2. Update to latest version\n3. Enable experimental features if needed\n4. Use alternative approach\n\n**Example Error Message:**\n```\n[BSIT-9003] Feature not implemented: parallel task execution is planned for v2.0\n```\n\n---\n\n## Quick Reference Table\n\n| Code | Name | Category |\n|------|------|----------|\n| BSIT-1001 | Node.js Version Mismatch | Installation |\n| BSIT-1002 | jq Not Found | Installation |\n| BSIT-1003 | Plugin Not Installed | Installation |\n| BSIT-1004 | SDK CLI Not Found | Installation |\n| BSIT-1005 | Git Not Available | Installation |\n| BSIT-2001 | Invalid Configuration | Configuration |\n| BSIT-2002 | Missing Runs Directory | Configuration |\n| BSIT-2003 | Invalid Log Level | Configuration |\n| BSIT-2004 | Configuration File Not Found | Configuration |\n| BSIT-2005 | Permission Denied | Configuration |\n| BSIT-3001 | Process Not Found | Runtime |\n| BSIT-3002 | Task Execution Failed | Runtime |\n| BSIT-3003 | Breakpoint Timeout | Runtime |\n| BSIT-3004 | Run Already Active | Runtime |\n| BSIT-3005 | Maximum Iterations Exceeded | Runtime |\n| BSIT-3006 | Agent Communication Failed | Runtime |\n| BSIT-4001 | Journal Corrupted | State |\n| BSIT-4002 | State File Missing | State |\n| BSIT-4003 | State File Invalid | State |\n| BSIT-4004 | Checkpoint Not Found | State |\n| BSIT-4005 | State Lock Acquisition Failed | State |\n| BSIT-5001 | Hook Not Found | Hook |\n| BSIT-5002 | Hook Not Executable | Hook |\n| BSIT-5003 | Hook Execution Failed | Hook |\n| BSIT-5004 | Hook Output Invalid | Hook |\n| BSIT-5005 | Hook Timeout | Hook |\n| BSIT-9001 | Unknown Error | Internal |\n| BSIT-9002 | Internal Error | Internal |\n| BSIT-9003 | Feature Not Implemented | Internal |\n\n---\n\n## Usage in Code\n\n### Shell Scripts\n\n```bash\nsource \"$PLUGIN_ROOT/scripts/error-codes.sh\"\n\n# Output an error\nbsit_error \"1002\" \"jq\" \"/usr/local/bin\"\n\n# Output a warning\nbsit_warn \"2003\" \"verbose\" \"debug, info, warn, error, silent\"\n\n# Get error message\nmsg=$(get_error_message \"3001\")\necho \"Error: $msg\"\n\n# Get recovery steps\nsteps=$(get_recovery_steps \"4001\")\necho \"Recovery: $steps\"\n```\n\n### JSON Error Format\n\nWhen outputting errors in JSON format:\n\n```json\n{\n  \"error\": {\n    \"code\": \"BSIT-3002\",\n    \"name\": \"Task Execution Failed\",\n    \"message\": \"Task 'build-project' failed with exit code 1\",\n    \"context\": {\n      \"taskId\": \"task-123\",\n      \"exitCode\": 1,\n      \"duration\": \"45s\"\n    },\n    \"recovery\": [\n      \"Check task logs: bsit logs --task task-123\",\n      \"Verify dependencies are installed\",\n      \"Retry with: bsit retry --task task-123\"\n    ]\n  }\n}\n```\n\n---\n\n## Adding New Error Codes\n\nWhen adding new error codes:\n\n1. Choose the appropriate category (1XXX-9XXX)\n2. Use the next available number in that category\n3. Document: code, name, description, causes, recovery, example\n4. Add to error-codes.sh helper script\n5. Update the quick reference table\n6. Test error output formatting\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}