Skip to main content

Babysitter Plugin Error Codes

This document defines the standardized error code system for the babysitter plugin.

Error Code Format​

All error codes follow the format: BSIT-XXXX

Code Categories​

RangeCategoryDescription
1XXXInstallation/SetupErrors related to installation, dependencies, and initial setup
2XXXConfigurationErrors related to configuration files and settings
3XXXRuntime/ExecutionErrors that occur during task execution
4XXXState/JournalErrors related to state management and journal files
5XXXHookErrors related to hook discovery and execution
9XXXUnknown/InternalUnexpected errors and internal failures

Installation/Setup Errors (1XXX)​

BSIT-1001: Node.js Version Mismatch​

Description: The installed Node.js version does not meet the minimum requirements.

Common Causes:

  • Node.js is outdated
  • Multiple Node.js versions installed with wrong one in PATH
  • nvm/fnm using an older version

Recovery Steps:

  1. Check current version: node --version
  2. Install Node.js 18.x or later from https://nodejs.org
  3. If using nvm: nvm install 18 && nvm use 18
  4. Verify: node --version

Example Error Message:

[BSIT-1001] Node.js version mismatch: found v16.20.0, required >=18.0.0

BSIT-1002: jq Not Found​

Description: The jq command-line JSON processor is not installed or not in PATH.

Common Causes:

  • jq not installed on the system
  • jq installed but not in PATH
  • Conda/virtualenv environment missing jq

Recovery Steps:

  1. Install jq:
    • macOS: brew install jq
    • Ubuntu/Debian: sudo apt-get install jq
    • Windows: choco install jq or winget install jqlang.jq
  2. Verify installation: jq --version
  3. Ensure jq is in your PATH

Example Error Message:

[BSIT-1002] Required dependency 'jq' not found. Install it with your package manager.

BSIT-1003: Plugin Not Installed​

Description: The babysitter plugin is not properly installed or registered with Claude Code.

Common Causes:

  • Plugin directory missing or moved
  • Plugin not registered in Claude Code settings
  • Corrupted installation

Recovery Steps:

  1. Verify plugin exists: ls -la ~/.claude/plugins/babysitter
  2. Re-register plugin: claude plugins add babysitter
  3. Restart Claude Code session
  4. Check plugin status: claude plugins list

Example Error Message:

[BSIT-1003] Babysitter plugin not installed. Run 'claude plugins add babysitter' to install.

BSIT-1004: SDK CLI Not Found​

Description: The babysitter SDK CLI (bsit or npx @a5c-ai/babysitter) is not available.

Common Causes:

  • SDK package not installed
  • npm global bin not in PATH
  • Package installation failed

Recovery Steps:

  1. Install the SDK: npm install -g @a5c-ai/babysitter
  2. Or use npx: npx @a5c-ai/babysitter --help
  3. Verify PATH includes npm global bin: npm bin -g
  4. Add to PATH if needed

Example Error Message:

[BSIT-1004] SDK CLI not found. Install with 'npm install -g @a5c-ai/babysitter'

BSIT-1005: Git Not Available​

Description: Git is not installed or not accessible in the current environment.

Common Causes:

  • Git not installed
  • Git not in PATH
  • Restricted shell environment

Recovery Steps:

  1. Install git from https://git-scm.com
  2. Verify: git --version
  3. Ensure git is in your PATH

Example Error Message:

[BSIT-1005] Git is required but not found in PATH. Install git and try again.

Configuration Errors (2XXX)​

BSIT-2001: Invalid Configuration​

Description: The configuration file contains invalid or malformed data.

Common Causes:

  • Syntax error in JSON/YAML configuration
  • Invalid field values
  • Missing required fields
  • Unsupported configuration version

Recovery Steps:

  1. Validate JSON syntax: jq . .a5c/config.json
  2. Check for required fields in documentation
  3. Reset to default: bsit config reset
  4. Re-run configuration wizard: bsit configure

Example Error Message:

[BSIT-2001] Invalid configuration in .a5c/config.json: unexpected token at line 15

BSIT-2002: Missing Runs Directory​

Description: The .a5c/runs directory does not exist and cannot be created.

Common Causes:

  • Directory was deleted
  • Permission issues
  • Disk full
  • Read-only filesystem

Recovery Steps:

  1. Create manually: mkdir -p .a5c/runs
  2. Check permissions: ls -la .a5c
  3. Verify disk space: df -h .
  4. Check filesystem is writable

Example Error Message:

[BSIT-2002] Runs directory not found and cannot be created: .a5c/runs

BSIT-2003: Invalid Log Level​

Description: The specified log level is not recognized.

Common Causes:

  • Typo in log level value
  • Using unsupported log level name
  • Environment variable set incorrectly

Recovery Steps:

  1. Use valid log levels: debug, info, warn, error, silent
  2. Check environment: echo $BABYSITTER_LOG_LEVEL
  3. Update configuration with valid level

Example Error Message:

[BSIT-2003] Invalid log level 'verbose'. Valid levels: debug, info, warn, error, silent

BSIT-2004: Configuration File Not Found​

Description: The expected configuration file does not exist.

Common Causes:

  • First run without initialization
  • Configuration file deleted
  • Wrong working directory

Recovery Steps:

  1. Initialize configuration: bsit init
  2. Check working directory contains .a5c folder
  3. Create default config: bsit config reset

Example Error Message:

[BSIT-2004] Configuration file not found: .a5c/config.json

BSIT-2005: Permission Denied​

Description: Cannot read or write to a required file or directory due to permissions.

Common Causes:

  • File owned by different user
  • Restrictive directory permissions
  • SELinux/AppArmor restrictions
  • Windows file locks

Recovery Steps:

  1. Check ownership: ls -la <path>
  2. Fix permissions: chmod 755 <directory> or chmod 644 <file>
  3. Check for file locks on Windows
  4. Run as appropriate user

Example Error Message:

[BSIT-2005] Permission denied: cannot write to .a5c/runs/current/state.json

Runtime/Execution Errors (3XXX)​

BSIT-3001: Process Not Found​

Description: The expected process file or definition could not be located.

Common Causes:

  • Process name misspelled
  • Process file deleted or moved
  • Process not installed with plugin
  • Custom process not in search path

Recovery Steps:

  1. List available processes: bsit process list
  2. Check process name spelling
  3. Verify process file exists in plugin/processes
  4. Add custom process path to configuration

Example Error Message:

[BSIT-3001] Process not found: 'tdd-quality-convergence'. Run 'bsit process list' to see available processes.

BSIT-3002: Task Execution Failed​

Description: A task failed to execute successfully.

Common Causes:

  • Task dependencies not met
  • External command failed
  • Timeout exceeded
  • Resource unavailable

Recovery Steps:

  1. Check task logs: bsit logs --run <run-id> --task <task-id>
  2. Verify task dependencies are satisfied
  3. Increase timeout if needed
  4. Check external service availability
  5. Retry with: bsit retry --task <task-id>

Example Error Message:

[BSIT-3002] Task execution failed: 'build-project' exited with code 1

BSIT-3003: Breakpoint Timeout​

Description: A breakpoint wait exceeded the maximum allowed time.

Common Causes:

  • User did not respond to breakpoint prompt
  • Network issues with notification
  • Claude Code session disconnected
  • Timeout set too low

Recovery Steps:

  1. Check for pending breakpoint notifications
  2. Resume manually: bsit resume --run <run-id>
  3. Increase timeout in configuration
  4. Check Claude Code session is active

Example Error Message:

[BSIT-3003] Breakpoint timeout after 300s waiting for user input at 'pre-deploy-approval'

BSIT-3004: Run Already Active​

Description: Attempted to start a new run while another is already active.

Common Causes:

  • Previous run not properly terminated
  • Concurrent babysitter invocations
  • Stale lock file

Recovery Steps:

  1. Check active runs: bsit status
  2. Stop active run: bsit stop --run <run-id>
  3. Force stop if needed: bsit stop --force
  4. Remove stale lock: rm .a5c/runs/.lock

Example Error Message:

[BSIT-3004] Run already active: run-2024-01-15-abc123. Stop it first with 'bsit stop'

BSIT-3005: Maximum Iterations Exceeded​

Description: The run exceeded the maximum number of allowed iterations.

Common Causes:

  • Infinite loop in process logic
  • Convergence criteria not achievable
  • Max iterations set too low
  • Process design issue

Recovery Steps:

  1. Review process logic for loops
  2. Check convergence criteria
  3. Increase max iterations if appropriate
  4. Analyze iteration logs for patterns

Example Error Message:

[BSIT-3005] Maximum iterations (100) exceeded. Process may be in infinite loop.

BSIT-3006: Agent Communication Failed​

Description: Failed to communicate with the AI agent.

Common Causes:

  • API rate limiting
  • Network connectivity issues
  • Invalid API credentials
  • Service outage

Recovery Steps:

  1. Check network connectivity
  2. Verify API credentials
  3. Check for rate limiting
  4. Retry after waiting
  5. Check service status page

Example Error Message:

[BSIT-3006] Agent communication failed: API returned 429 (rate limited). Retry after 60s.

State/Journal Errors (4XXX)​

BSIT-4001: Journal Corrupted​

Description: The run journal file is corrupted or contains invalid data.

Common Causes:

  • Interrupted write operation
  • Disk error
  • Manual editing introduced errors
  • Concurrent writes without locking

Recovery Steps:

  1. Check journal file: jq . .a5c/runs/<run-id>/journal.json
  2. Restore from backup: cp .a5c/runs/<run-id>/journal.json.bak .a5c/runs/<run-id>/journal.json
  3. Recreate from state: bsit repair --run <run-id>
  4. Start fresh run if unrecoverable

Example Error Message:

[BSIT-4001] Journal corrupted: .a5c/runs/run-abc123/journal.json - invalid JSON at offset 4521

BSIT-4002: State File Missing​

Description: A required state file is missing from the run directory.

Common Causes:

  • File accidentally deleted
  • Incomplete run initialization
  • Storage failure
  • Cleanup ran prematurely

Recovery Steps:

  1. Check run directory: ls -la .a5c/runs/<run-id>/
  2. Restore from backup if available
  3. Reinitialize state: bsit init-state --run <run-id>
  4. Start new run if state unrecoverable

Example Error Message:

[BSIT-4002] State file missing: .a5c/runs/run-abc123/state/current.json

BSIT-4003: State File Invalid​

Description: The state file exists but contains invalid or inconsistent data.

Common Causes:

  • Schema version mismatch
  • Incomplete state update
  • Manual editing errors
  • Serialization bug

Recovery Steps:

  1. Validate state file: bsit validate --run <run-id>
  2. Compare with schema: Check state file against expected schema
  3. Reset to last checkpoint: bsit rollback --run <run-id>
  4. Repair state: bsit repair --run <run-id>

Example Error Message:

[BSIT-4003] State file invalid: missing required field 'iteration' in state/current.json

BSIT-4004: Checkpoint Not Found​

Description: The requested checkpoint does not exist.

Common Causes:

  • Checkpoint ID incorrect
  • Checkpoints not enabled
  • Checkpoint was cleaned up
  • No checkpoints created yet

Recovery Steps:

  1. List checkpoints: bsit checkpoints --run <run-id>
  2. Verify checkpoint ID spelling
  3. Check checkpoint retention settings
  4. Create manual checkpoint: bsit checkpoint create

Example Error Message:

[BSIT-4004] Checkpoint not found: checkpoint-5. Available: checkpoint-1, checkpoint-2, checkpoint-3

BSIT-4005: State Lock Acquisition Failed​

Description: Could not acquire lock on state files for writing.

Common Causes:

  • Another process holds the lock
  • Stale lock file
  • Permission issues
  • Lock timeout too short

Recovery Steps:

  1. Check for other babysitter processes: ps aux | grep babysitter
  2. Remove stale lock: rm .a5c/runs/<run-id>/.lock
  3. Wait and retry
  4. Increase lock timeout

Example Error Message:

[BSIT-4005] State lock acquisition failed after 30s. Lock held by PID 12345.

Hook Errors (5XXX)​

BSIT-5001: Hook Not Found​

Description: The specified hook file does not exist.

Common Causes:

  • Hook file deleted
  • Wrong hook path in configuration
  • Hook type directory missing
  • Case sensitivity issues

Recovery Steps:

  1. Check hook exists: ls -la plugins/babysitter-unified/hooks/<hook-type>.sh
  2. Verify hook path in configuration
  3. Create hook directory: mkdir -p hooks/<hook-type>
  4. Reinstall plugin if hooks missing

Example Error Message:

[BSIT-5001] Hook not found: hooks/on-task-complete/custom-notify.sh

BSIT-5002: Hook Not Executable​

Description: The hook file exists but is not executable.

Common Causes:

  • Missing execute permission
  • Wrong file type (not a script)
  • Windows permission issues
  • Git not preserving permissions

Recovery Steps:

  1. Add execute permission: chmod +x <hook-file>
  2. On Windows, check file association
  3. Verify shebang line: First line should be #!/bin/bash or similar
  4. Git: git update-index --chmod=+x <hook-file>

Example Error Message:

[BSIT-5002] Hook not executable: hooks/on-run-start/logger.sh. Run 'chmod +x' to fix.

BSIT-5003: Hook Execution Failed​

Description: The hook script exited with a non-zero status.

Common Causes:

  • Script error (syntax or runtime)
  • Missing dependencies in hook
  • Environment variables not set
  • External service failure

Recovery Steps:

  1. Run hook manually to see error: bash -x <hook-file>
  2. Check hook logs: cat .a5c/runs/<run-id>/hooks.log
  3. Verify hook dependencies
  4. Test hook in isolation

Example Error Message:

[BSIT-5003] Hook execution failed: on-task-complete/metrics.sh exited with code 127 (command not found)

BSIT-5004: Hook Output Invalid​

Description: The hook produced output that could not be parsed or was invalid.

Common Causes:

  • Hook output is not valid JSON (when JSON expected)
  • Output exceeds size limit
  • Encoding issues
  • Mixed stdout/stderr

Recovery Steps:

  1. Test hook output: <hook-file> | jq .
  2. Ensure hook outputs only JSON to stdout
  3. Redirect debug output to stderr
  4. Check output encoding is UTF-8

Example Error Message:

[BSIT-5004] Hook output invalid: on-breakpoint/cli.sh - expected JSON, got plain text

BSIT-5005: Hook Timeout​

Description: The hook execution exceeded the maximum allowed time.

Common Causes:

  • Hook waiting for user input
  • Network request hanging
  • Infinite loop in hook
  • External service slow

Recovery Steps:

  1. Review hook for blocking operations
  2. Add timeouts to external calls
  3. Increase hook timeout in configuration
  4. Make hook asynchronous if possible

Example Error Message:

[BSIT-5005] Hook timeout: on-run-complete/notify.sh exceeded 30s limit

Unknown/Internal Errors (9XXX)​

BSIT-9001: Unknown Error​

Description: An unexpected error occurred that doesn't match any known error pattern.

Common Causes:

  • Unhandled exception
  • System-level failure
  • Memory/resource exhaustion
  • Bug in babysitter code

Recovery Steps:

  1. Check full error logs: bsit logs --verbose
  2. Check system resources (disk, memory)
  3. Try restarting the operation
  4. Report bug with logs at https://github.com/a5c-ai/babysitter/issues

Example Error Message:

[BSIT-9001] Unknown error occurred. See logs for details. Please report this issue.

BSIT-9002: Internal Error​

Description: An internal error occurred in the babysitter code.

Common Causes:

  • Bug in babysitter code
  • Assertion failure
  • Invalid internal state
  • Race condition

Recovery Steps:

  1. Save current state/logs for bug report
  2. Try operation again
  3. Update to latest babysitter version
  4. Report bug with reproduction steps

Example Error Message:

[BSIT-9002] Internal error: assertion failed in StateManager.commit() - expected state to be initialized

BSIT-9003: Feature Not Implemented​

Description: The requested feature is not yet implemented.

Common Causes:

  • Using development/preview feature
  • Feature planned for future release
  • Experimental flag not enabled

Recovery Steps:

  1. Check documentation for feature availability
  2. Update to latest version
  3. Enable experimental features if needed
  4. Use alternative approach

Example Error Message:

[BSIT-9003] Feature not implemented: parallel task execution is planned for v2.0

Quick Reference Table​

CodeNameCategory
BSIT-1001Node.js Version MismatchInstallation
BSIT-1002jq Not FoundInstallation
BSIT-1003Plugin Not InstalledInstallation
BSIT-1004SDK CLI Not FoundInstallation
BSIT-1005Git Not AvailableInstallation
BSIT-2001Invalid ConfigurationConfiguration
BSIT-2002Missing Runs DirectoryConfiguration
BSIT-2003Invalid Log LevelConfiguration
BSIT-2004Configuration File Not FoundConfiguration
BSIT-2005Permission DeniedConfiguration
BSIT-3001Process Not FoundRuntime
BSIT-3002Task Execution FailedRuntime
BSIT-3003Breakpoint TimeoutRuntime
BSIT-3004Run Already ActiveRuntime
BSIT-3005Maximum Iterations ExceededRuntime
BSIT-3006Agent Communication FailedRuntime
BSIT-4001Journal CorruptedState
BSIT-4002State File MissingState
BSIT-4003State File InvalidState
BSIT-4004Checkpoint Not FoundState
BSIT-4005State Lock Acquisition FailedState
BSIT-5001Hook Not FoundHook
BSIT-5002Hook Not ExecutableHook
BSIT-5003Hook Execution FailedHook
BSIT-5004Hook Output InvalidHook
BSIT-5005Hook TimeoutHook
BSIT-9001Unknown ErrorInternal
BSIT-9002Internal ErrorInternal
BSIT-9003Feature Not ImplementedInternal

Usage in Code​

Shell Scripts​

source "$PLUGIN_ROOT/scripts/error-codes.sh"

# Output an error
bsit_error "1002" "jq" "/usr/local/bin"

# Output a warning
bsit_warn "2003" "verbose" "debug, info, warn, error, silent"

# Get error message
msg=$(get_error_message "3001")
echo "Error: $msg"

# Get recovery steps
steps=$(get_recovery_steps "4001")
echo "Recovery: $steps"

JSON Error Format​

When outputting errors in JSON format:

{
  "error": {
    "code": "BSIT-3002",
    "name": "Task Execution Failed",
    "message": "Task 'build-project' failed with exit code 1",
    "context": {
      "taskId": "task-123",
      "exitCode": 1,
      "duration": "45s"
    },
    "recovery": [
      "Check task logs: bsit logs --task task-123",
      "Verify dependencies are installed",
      "Retry with: bsit retry --task task-123"
    ]
  }
}

Adding New Error Codes​

When adding new error codes:

  1. Choose the appropriate category (1XXX-9XXX)
  2. Use the next available number in that category
  3. Document: code, name, description, causes, recovery, example
  4. Add to error-codes.sh helper script
  5. Update the quick reference table
  6. Test error output formatting