Skip to content

error-catalog.md

Latest commit

 

History

History
735 lines (555 loc) · 13.7 KB

error-catalog.md

File metadata and controls

735 lines (555 loc) · 13.7 KB

Error Catalog

Version: 1.0 Last Updated: 2026-01-25 Category: Reference

This catalog provides comprehensive documentation of Babysitter error messages, their meanings, causes, and solutions.

Table of Contents

Installation Errors

ERR_MODULE_NOT_FOUND

Error: Cannot find module '@a5c-ai/babysitter-sdk'

Meaning: The Babysitter SDK package is not installed or not accessible.

Causes:

  • SDK not installed globally
  • npm global path not in system PATH
  • Wrong Node.js version active

Solutions:

  1. Install globally: 
    npm install -g @a5c-ai/babysitter-sdk@latest
  2. Use npx: 
    npx -y @a5c-ai/babysitter-sdk@latest --version
  3. Check PATH includes npm global bin: 
    npm bin -g
# Add to PATH if needed

EACCES: permission denied

npm ERR! EACCES: permission denied, mkdir '/usr/local/lib/node_modules/...'

Meaning: npm doesn't have permission to write to the global packages directory.

Causes:

  • npm configured to use system directory
  • Insufficient permissions
  • Previous sudo install

Solutions:

  1. Configure npm for user installs: 
    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
  2. Retry installation: 
    npm install -g @a5c-ai/babysitter-sdk@latest

ERESOLVE: unable to resolve dependency tree

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! Could not resolve dependency: @a5c-ai/babysitter-sdk@^0.0.120

Meaning: Version conflicts between Babysitter packages.

Causes:

  • Mixed versions of packages
  • Outdated package in cache
  • Conflicting peer dependencies

Solutions:

  1. Update all packages together: 
    npm install -g @a5c-ai/babysitter-sdk@latest
  2. Clear npm cache if needed: 
    npm cache clean --force

Plugin Errors

Plugin not found: babysitter@a5c.ai

Error: Plugin 'babysitter@a5c.ai' not found
Available plugins: [...]

Meaning: The Babysitter plugin is not installed in Claude Code.

Causes:

  • Plugin not installed
  • Marketplace not added
  • Plugin disabled

Solutions:

  1. Add marketplace: 
    claude plugin marketplace add a5c-ai/babysitter
  2. Install plugin: 
    claude plugin install --scope user babysitter@a5c.ai
  3. Enable plugin: 
    claude plugin enable --scope user babysitter@a5c.ai
  4. Restart Claude Code

Skill not found: babysit

Error: Skill 'babysit' not found

Meaning: The babysit skill is not available in the current session.

Causes:

  • Plugin not enabled
  • Claude Code not restarted after plugin install
  • Plugin load error

Solutions:

  1. Check plugin status: 
    claude plugin list | grep babysitter
  2. Enable if disabled: 
    claude plugin enable --scope user babysitter@a5c.ai
  3. Restart Claude Code completely
  4. Verify with /skills

Plugin load error

Error loading plugin babysitter@a5c.ai: [details]

Meaning: The plugin failed to initialize.

Causes:

  • Corrupted plugin files
  • Version incompatibility
  • Missing dependencies

Solutions:

  1. Reinstall plugin: 
    claude plugin uninstall babysitter@a5c.ai
claude plugin install --scope user babysitter@a5c.ai
  2. Update marketplace: 
    claude plugin marketplace update a5c.ai
  3. Check for updates: 
    claude plugin update babysitter@a5c.ai

Run Execution Errors

Run encountered an error

Error: Run encountered an error
  at processIteration (process.js:123)
  Caused by: [underlying error]

Meaning: The run failed during execution.

Causes:

  • Task failure
  • Journal conflict
  • Process definition error
  • External dependency failure

Solutions:

  1. Check journal for details: 
    What error caused my babysitter run to fail?
  2. Fix underlying issue
  3. Resume if possible: 
    /babysitter:call resume

Run not found

Error: Run not found: 01KFFTSF8TK8C9GT3YM9QYQ6WG

Meaning: The specified run ID doesn't exist.

Causes:

  • Run was deleted
  • Wrong run ID
  • Wrong working directory
  • Run never created

Solutions:

  1. Ask Claude to find available runs: 
    What babysitter runs have I done recently?
  2. Check working directory
  3. Use correct run ID

Run already completed

Error: Cannot resume completed run
Run state: completed

Meaning: Attempting to resume a run that has already finished.

Causes:

  • Run finished successfully
  • Trying to resume wrong run

Solutions:

  • Completed runs cannot be resumed
  • Create a new run for additional work

Run is already being executed

Error: Run is already being executed by another session

Meaning: Another session is actively running this workflow.

Causes:

  • Multiple Claude Code windows running same workflow
  • Previous session didn't terminate cleanly

Solutions:

  1. Wait for other session to complete
  2. Close other Claude Code sessions
  3. Wait a moment and retry (for stale locks)

Task Execution Errors

ENOENT: no such file or directory

Error: ENOENT: no such file or directory, open '/path/to/file.js'
Task failed: task-001

Meaning: A task tried to access a file that doesn't exist.

Causes:

  • Incorrect file path in task definition
  • File deleted or moved
  • Path resolution issue
  • Dependencies not installed

Solutions:

  1. Verify file exists: 
    ls -la /path/to/file.js
  2. Check paths in task definition
  3. Install missing dependencies: 
    npm install

Task timeout

Error: Task timeout: agent-task-001
Execution exceeded 120s

Meaning: A task took too long to complete.

Causes:

  • Large context for agent task
  • API latency
  • Complex computation
  • Network issues

Solutions:

  1. Reduce task scope
  2. Increase timeout: 
    await ctx.task(task, args, { timeout: 300000 });
  3. Check API status
  4. Split into smaller tasks

Task failed with exit code

Error: Task failed with exit code 1
Command: npm test
stderr: [error output]

Meaning: A shell/node task command failed.

Causes:

  • Test failures
  • Build errors
  • Missing dependencies
  • Script errors

Solutions:

  1. Check stderr for details
  2. Run command manually to debug: 
    npm test
  3. Fix underlying issues
  4. Resume run

Agent task error

Error: Agent task failed
  Caused by: API rate limit exceeded

Meaning: The LLM API call failed.

Causes:

  • Rate limiting
  • API outage
  • Invalid request
  • Token limit exceeded

Solutions:

  1. Wait and retry (for rate limits)
  2. Check API status
  3. Reduce context size
  4. Resume run after waiting

Quality and Scoring Errors

Quality target not met

Quality target not met after 5 iterations
Final score: 78/100
Target: 85/100

Meaning: The quality convergence loop couldn't reach the target score.

Causes:

  • Unrealistic target
  • Fundamental code issues
  • Scoring criteria too strict
  • Not enough iterations

Solutions:

  1. Lower quality target: 
    Use babysitter with 75% quality target
  2. Increase iterations: 
    Use babysitter with max 10 iterations
  3. Review and fix blocking issues
  4. Adjust scoring weights

Quality score validation error

Error: Invalid quality score returned by agent
Expected: number between 0-100
Received: [invalid value]

Meaning: The scoring agent returned an invalid score.

Causes:

  • Agent prompt issue
  • Response parsing error
  • Schema mismatch

Solutions:

  1. Check agent task definition
  2. Verify output schema
  3. Review agent prompt for clarity

Journal and State Errors

Journal conflict detected

Error: Journal conflict detected
Multiple writes attempted at sequence 42

Meaning: Concurrent writes to the journal were detected.

Causes:

  • Multiple sessions running same workflow
  • Race condition
  • Stale lock

Solutions:

  1. Ensure single session per run
  2. Close other Claude Code windows
  3. Wait and retry
  4. Delete state cache and rebuild: 
    rm .a5c/runs/<runId>/state/state.json
babysitter run:status <runId>

Journal integrity error

Error: Journal integrity check failed
Event 43 has invalid sequence

Meaning: The journal has inconsistent or corrupted data.

Causes:

  • Manual journal editing
  • Disk write failure
  • Interrupted write
  • File corruption

Solutions:

  1. Check journal files: 
    jq empty .a5c/runs/<runId>/journal/*.json
  2. If corrupted, may need to start new run
  3. Backup and investigate: 
    cp -r .a5c/runs/<runId> backup-run

State reconstruction failed

Error: Failed to reconstruct state from journal
Invalid event at sequence 15

Meaning: The state cache couldn't be rebuilt from journal events.

Causes:

  • Corrupted journal
  • Missing events
  • Invalid event format

Solutions:

  1. Delete state cache: 
    rm .a5c/runs/<runId>/state/state.json
  2. Check journal integrity
  3. May need to start new run if journal corrupted

Network and API Errors

ETIMEDOUT

Error: connect ETIMEDOUT 104.26.0.100:443

Meaning: Network connection timed out.

Causes:

  • Network issues
  • Firewall blocking
  • Service unavailable
  • DNS issues

Solutions:

  1. Check internet connectivity
  2. Verify service is accessible
  3. Check firewall settings
  4. Retry after network recovery

API rate limit exceeded

Error: API rate limit exceeded
Retry after: 60 seconds

Meaning: Too many API requests in a short period.

Causes:

  • High-frequency requests
  • Concurrent tasks making requests
  • Account rate limits

Solutions:

  1. Wait and retry
  2. Reduce parallel API calls
  3. Add delays between requests
  4. Check account rate limits

SSL/TLS error

Error: unable to verify the first certificate

Meaning: SSL certificate verification failed.

Causes:

  • Certificate issues
  • Proxy interference
  • Outdated certificates

Solutions:

  1. Check system time is correct
  2. Update CA certificates
  3. Check proxy settings
  4. Don't disable SSL verification (security risk)

File System Errors

ENOSPC: no space left on device

Error: ENOSPC: no space left on device

Meaning: Disk is full.

Causes:

  • Many large runs
  • Large artifacts
  • System disk full

Solutions:

  1. Clean old runs: 
    rm -rf .a5c/runs/<old-run-id>
  2. Check disk space: 
    df -h
  3. Free space on disk

EPERM: operation not permitted

Error: EPERM: operation not permitted, open '/path/to/file'

Meaning: Insufficient permissions for file operation.

Causes:

  • File permissions
  • Read-only file system
  • File locked by another process

Solutions:

  1. Check file permissions: 
    ls -la /path/to/file
  2. Fix permissions if needed
  3. Check for file locks

EMFILE: too many open files

Error: EMFILE: too many open files

Meaning: System file descriptor limit reached.

Causes:

  • Many concurrent file operations
  • System limit too low
  • File handles not closed

Solutions:

  1. Increase ulimit: 
    ulimit -n 4096
  2. Close other applications
  3. Reduce concurrent operations

Error Codes Reference

Quick Reference Table

Error Code Category Common Cause Quick Fix
ENOENT File System File not found Check paths
EACCES Permissions No permission Fix permissions
EADDRINUSE Network Port in use Kill process or change port
ECONNREFUSED Network Service not running Start service
ETIMEDOUT Network Connection timeout Check network
ENOSPC File System Disk full Free space
EPERM Permissions Operation denied Check permissions
EMFILE System Too many files Increase ulimit
ERR_MODULE_NOT_FOUND Node.js Module missing Install package
ERESOLVE npm Dependency conflict Update packages

Exit Codes

Exit Code Meaning Action
0 Success None needed
1 General error Check error message
2 Command not found Check installation
126 Permission denied Fix permissions
127 Command not found Check PATH
137 Out of memory (SIGKILL) Increase memory
143 Terminated (SIGTERM) Check what terminated

Related Documentation

Reporting New Errors

If you encounter an error not listed here:

  1. Document the error:

    • Full error message
    • Stack trace (if available)
    • Steps to reproduce

  2. Gather diagnostics:

    babysitter run:status <runId> --json > diagnostic.json
babysitter run:events <runId> --limit 20 --reverse --json >> diagnostic.json

  3. Report at: GitHub Issues

Document Status: Complete Last Updated: 2026-01-25