Error Catalog

June 23, 2026 · View on GitHub

Docs › Reference › Error Catalog

Error Catalog

Version: 1.0 Last Updated: 2026-06-22 Category: Reference

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

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 to the current project.

Causes:

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

Solutions:

Install globally:

npm install -g @a5c-ai/babysitter@latest

Use npx:

npx -y @a5c-ai/babysitter@latest --version

If your process code imports the SDK, install it in the project:
```
npm install @a5c-ai/babysitter-sdk
```
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:

Configure npm for user installs:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Retry installation:

npm install -g @a5c-ai/babysitter@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@^4.0.0

Meaning: Version conflicts between Babysitter packages.

Causes:

Mixed versions of packages
Outdated package in cache
Conflicting peer dependencies

Solutions:

Update all packages together:

npm install -g @a5c-ai/babysitter@latest @a5c-ai/genty-platform@latest

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:

Add marketplace:

claude plugin marketplace add a5c-ai/babysitter-claude

Install plugin:

claude plugin install --scope user babysitter@a5c.ai

Enable plugin:

claude plugin enable --scope user babysitter@a5c.ai

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:

Check plugin status:
```
claude plugin list | grep babysitter
```

Enable if disabled:

claude plugin enable --scope user babysitter@a5c.ai

Restart Claude Code completely
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:

Reinstall plugin:

claude plugin uninstall babysitter@a5c.ai
claude plugin install --scope user babysitter@a5c.ai

Update marketplace:

claude plugin marketplace update a5c.ai

Check for updates:
```
claude plugin update babysitter@a5c.ai
```

The host-side adapters CLI (package @a5c-ai/adapters-cli) is the harness runtime companion. When it cannot start, find a harness, or reach a provider, you will see one of the following. See the Adapters CLI Reference for the full command surface.

adapters: command not found

adapters: command not found

Meaning: The adapters CLI is not installed or not on your PATH.

Causes:

@a5c-ai/adapters-cli not installed globally
npm global bin not on PATH

Solutions:

Install globally:
```
npm install -g @a5c-ai/adapters-cli
```
Confirm the install and environment:
```
adapters version
adapters doctor
```
Ensure the npm global bin is on PATH:
```
npm bin -g
```

Unsupported Node.js version (adapters)

Error: @a5c-ai/adapters-cli requires Node.js >=20.9.0

Meaning: The adapters CLI pins a higher Node floor (>=20.9.0) than the rest of the Babysitter toolchain (>=20.0.0).

Causes:

An older Node.js is active in the current shell
A version manager (nvm/asdf) selected an out-of-range version

Solutions:

Check the active version:
```
node --version
```
Switch to a supported version (22.x LTS recommended):
```
nvm install 22 && nvm use 22
```

Adapter not found / harness binary missing

Error: adapter not found for agent 'codex'

Error: harness binary for 'gemini' not detected

Meaning: The requested adapter is not registered, or its underlying harness binary cannot be located.

Causes:

The harness CLI is not installed
Wrong agent/adapter name
Credentials or PATH issues hiding the binary

Solutions:

Run the environment health check first:
```
adapters doctor
```

List and inspect registered adapters:

adapters adapters list
adapters adapters detect codex

Install the missing harness binary:
```
adapters install codex
```

Provider transport error

Error: harness cannot speak provider transport natively

Meaning: The harness cannot reach the requested provider (Bedrock, Vertex, Azure Foundry, Ollama, and others) without a transport proxy.

Causes:

Harness does not natively support the provider's transport
Proxy disabled with --no-proxy

Solutions:

Let the launcher start a proxy when needed:

adapters launch claude bedrock --with-proxy-if-needed

Verify credentials with adapters auth check.

Harness Install Errors

These surface when installing the in-session /babysitter:* plugin into a harness with babysitter harness:install-plugin <harness-key>. See the Install Matrix for the authoritative list of harness keys.

Unknown harness key

Error: unknown harness key 'gemini'

Meaning: The argument passed to harness:install-plugin is not a recognized harness key.

Causes:

Using the harness display name instead of its key (e.g. gemini instead of gemini-cli)
Typo in the key

Solutions:

Use the correct harness key — it is not always the harness name:
```
babysitter harness:install-plugin gemini-cli
```
Check the Install Matrix for every supported key.

Plugin installed but not appearing in the harness

Plugin installed, but /babysitter:* commands are not available

Meaning: The install completed but the harness has not picked up the plugin.

Causes:

Harness not restarted after install
Installed into the wrong workspace
The harness uses a different continuation/registration model than expected

Solutions:

Restart the harness completely.

Re-run the install targeting the right workspace:

babysitter harness:install-plugin <harness-key> --workspace ./my-project

Confirm which continuation model the harness uses in the Hooks per-harness table — do not assume the Claude Stop-hook model elsewhere.

See: Troubleshooting - Harness Install Issues.

Session Binding Errors

In v6, session resolution is PID-scoped and harness-agnostic. The session ID is carried in AGENT_SESSION_ID (which supersedes the deprecated BABYSITTER_SESSION_ID and CLAUDE_SESSION_ID). See Configuration for the full variable list.

Session not bound / cannot resolve session

Error: could not resolve agent session for this process

Meaning: Babysitter could not bind the current process to a harness session.

Causes:

The harness did not export AGENT_SESSION_ID
The continuation hook is not registered for this harness
A wrapper process broke the PID-scoped lookup

Solutions:

Confirm the session variable is present:
```
echo "$AGENT_SESSION_ID"
```
If your harness sets the session only via the environment (not via the PID-scoped store), opt into the legacy behavior with the escape hatch:
```
export BABYSITTER_TRUST_ENV_SESSION=1
```
Verify the harness's continuation hooks are installed (see Hooks).

See: Troubleshooting - Session Binding Issues.

Deprecated session variable in use

Warning: BABYSITTER_SESSION_ID is deprecated; use AGENT_SESSION_ID

Meaning: A removed/deprecated session variable was detected.

Causes:

Scripts or configs still set BABYSITTER_SESSION_ID or CLAUDE_SESSION_ID

Solutions:

Replace the deprecated variables with AGENT_SESSION_ID.
Remove any --plugin-root flag from scripts — it has been removed and plugin-root resolution is now automatic (the runtime injects BABYSITTER_PLUGIN_ROOT into hooks; you do not set it yourself).

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:

Check journal for details:

What error caused my babysitter run to fail?

Fix underlying issue
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:

Ask Claude to find available runs:

What babysitter runs have I done recently?

Check working directory
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:

Wait for other session to complete
Close other Claude Code sessions
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:

Verify file exists:
```
ls -la /path/to/file.js
```
Check paths in task definition
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:

Reduce task scope

Increase timeout:

await ctx.task(task, args, { timeout: 300000 });

Check API status
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:

Check stderr for details
Run command manually to debug:
```
npm test
```
Fix underlying issues
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:

Wait and retry (for rate limits)
Check API status
Reduce context size
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:

Lower quality target:
```
Use babysitter with 75% quality target
```
Increase iterations:
```
Use babysitter with max 10 iterations
```
Review and fix blocking issues
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:

Check agent task definition
Verify output schema
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:

Ensure single session per run
Close other Claude Code windows
Wait and retry

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:

Check journal files:

jq empty .a5c/runs/<runId>/journal/*.json

If corrupted, may need to start new run
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:

Delete state cache:
```
rm .a5c/runs/<runId>/state/state.json
```
Check journal integrity
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:

Check internet connectivity
Verify service is accessible
Check firewall settings
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:

Wait and retry
Reduce parallel API calls
Add delays between requests
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:

Check system time is correct
Update CA certificates
Check proxy settings
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:

Clean old runs:
```
rm -rf .a5c/runs/<old-run-id>
```
Check disk space:
```
df -h
```
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:

Check file permissions:
```
ls -la /path/to/file
```
Fix permissions if needed
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:

Increase ulimit:
```
ulimit -n 4096
```
Close other applications
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

Troubleshooting Guide - Step-by-step problem resolution
Configuration Reference - Environment variables (including AGENT_SESSION_ID and BABYSITTER_TRUST_ENV_SESSION)
Adapters CLI Reference - The host-side adapters CLI
FAQ - Common questions answered
Installation Guide - Setup help

Reporting New Errors

If you encounter an error not listed here:

Document the error:
- Full error message
- Stack trace (if available)
- Steps to reproduce

Gather diagnostics:

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

Report at: GitHub Issues

Next steps

Next: Troubleshooting
Related: FAQ, CLI Reference

Document Status: Complete Last Updated: 2026-06-22