Troubleshooting

Name: stdio Bus
Author: stdio Bus

Common issues, debugging techniques, and solutions for stdio Bus workers.

Getting Started

Integration

Reference

Overview

This guide covers common issues encountered when working with stdio Bus workers, along with solutions and debugging techniques.

Installation Issues

Node.js Version Mismatch

Symptom: Installation fails with Node.js version error

Error message:

error @stdiobus/workers-registry@0.1.0: The engine "node" is incompatible with this module. Expected version ">=20.0.0". Got "18.0.0"

Code block in Text, 1 line

Solution:

# Check current Node.js version
node --version
 
# Install Node.js 20 or later
# Using nvm (recommended)
nvm install 20
nvm use 20
 
# Or download from nodejs.org
# https://nodejs.org/

Code block in Bash, 10 lines

Permission Errors

Symptom: Permission denied during installation

Error message:

EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@stdiobus'

Code block in Text, 1 line

Solution:

# Option 1: Use npx (recommended)
npx @stdiobus/workers-registry
 
# Option 2: Install locally (no sudo needed)
npm install @stdiobus/workers-registry
 
# Option 3: Fix npm permissions
# https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

Code block in Bash, 8 lines

Package Not Found

Symptom: Cannot find package

Error message:

npm ERR! 404 Not Found - GET https://registry.npmjs.org/@stdiobus%2fworkers-registry

Code block in Text, 1 line

Solution:

# Verify package name (case-sensitive)
npm install @stdiobus/workers-registry
 
# Check npm registry
npm config get registry
 
# Clear npm cache
npm cache clean --force
npm install @stdiobus/workers-registry

Code block in Bash, 9 lines

Build Errors

Symptom: TypeScript compilation errors during installation

Solution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
 
# Verify TypeScript version
npm list typescript
 
# Install TypeScript if missing
npm install --save-dev typescript@5

Code block in Bash, 9 lines

Runtime Issues

Worker Not Starting

Symptom: Worker process fails to start

Debugging steps:

1. Check command path:

# Verify worker executable exists
ls -la node_modules/@stdiobus/workers-registry/out/dist/index.js
 
# Test worker directly
node node_modules/@stdiobus/workers-registry/out/dist/index.js echo-worker

Code block in Bash, 5 lines

2. Check configuration:

# Validate JSON syntax
cat config.json | jq .
 
# Check for typos in worker names
# Valid: acp-worker, registry-launcher, mcp-to-acp-proxy, echo-worker, mcp-echo-server

Code block in Bash, 5 lines

3. Check permissions:

# Verify execute permissions
chmod +x node_modules/@stdiobus/workers-registry/out/dist/index.js
 
# Check file ownership
ls -la node_modules/@stdiobus/workers-registry/out/dist/

Code block in Bash, 5 lines

4. Check environment:

# Verify Node.js is in PATH
which node
 
# Check Node.js version
node --version
 
# Test with absolute path
/usr/local/bin/node node_modules/@stdiobus/workers-registry/out/dist/index.js echo-worker

Code block in Bash, 8 lines

Worker Crashes

Symptom: Worker process crashes repeatedly

Debugging steps:

1. Check stdio Bus logs:

# Docker logs
docker logs <container-name>
 
# Binary logs (if using systemd)
journalctl -u stdiobus -f
 
# Check for crash patterns
docker logs <container-name> 2>&1 | grep -i "error\|crash\|fatal"

Code block in Bash, 8 lines

2. Check worker stderr:

# Workers log to stderr
# Look for error messages in stdio Bus logs
docker logs <container-name> 2>&1 | grep -A 5 "worker-id"

Code block in Bash, 3 lines

3. Increase restart limits:

{
  "limits": {
    "max_restarts": 10,
    "restart_window_sec": 120
  }
}

Code block in JSON, 6 lines

4. Test worker standalone:

# Run worker directly to see errors
echo '{"jsonrpc":"2.0","id":"1","method":"test","params":{}}' | \
  node node_modules/@stdiobus/workers-registry/out/dist/index.js echo-worker

Code block in Bash, 3 lines

Connection Refused

Symptom: Cannot connect to stdio Bus

Error message:

Error: connect ECONNREFUSED 127.0.0.1:9000

Code block in Text, 1 line

Debugging steps:

1. Check if stdio Bus is running:

# Check process
ps aux | grep stdio_bus
 
# Check Docker container
docker ps | grep stdiobus
 
# Check port binding
netstat -an | grep 9000
# Or on macOS
lsof -i :9000

Code block in Bash, 10 lines

2. Verify port configuration:

# Check stdio Bus startup command
docker logs <container-name> | grep "Listening"
 
# Verify port is exposed
docker port <container-name>

Code block in Bash, 5 lines

3. Check firewall:

# Linux (iptables)
sudo iptables -L -n | grep 9000
 
# macOS (pf)
sudo pfctl -s rules | grep 9000
 
# Allow port if blocked
sudo ufw allow 9000/tcp

Code block in Bash, 8 lines

4. Test connection:

# Test TCP connection
nc -zv localhost 9000
 
# Test with telnet
telnet localhost 9000
 
# Send test message
echo '{"jsonrpc":"2.0","id":"1","method":"test","params":{}}' | nc localhost 9000

Code block in Bash, 8 lines

Session Affinity Not Working

Symptom: Messages with same sessionId go to different workers

Debugging steps:

1. Verify sessionId in requests:

# Check request format
echo '{"jsonrpc":"2.0","id":"1","method":"test","sessionId":"sess-123","params":{}}' | nc localhost 9000

Code block in Bash, 2 lines

2. Check worker responses:

# Verify worker preserves sessionId
# Response should include: "sessionId":"sess-123"

Code block in Bash, 2 lines

3. Check worker instances:

{
  "pools": [
    {
      "id": "acp-registry",
      "instances": 4  // Multiple instances required for session affinity
    }
  ]
}

Code block in JSON, 8 lines

4. Enable debug logging:

# Check stdio Bus logs for routing decisions
docker logs <container-name> 2>&1 | grep -i "session"

Code block in Bash, 2 lines

Memory Issues

Symptom: Worker or stdio Bus running out of memory

Debugging steps:

1. Check memory usage:

# Docker container memory
docker stats <container-name>
 
# Process memory
ps aux | grep stdio_bus
ps aux | grep node

Code block in Bash, 6 lines

2. Adjust buffer limits:

{
  "limits": {
    "max_input_buffer": 524288,    // Reduce from 1MB
    "max_output_queue": 2097152    // Reduce from 4MB
  }
}

Code block in JSON, 6 lines

3. Reduce worker instances:

{
  "pools": [
    {
      "id": "acp-registry",
      "instances": 2  // Reduce from 4
    }
  ]
}

Code block in JSON, 8 lines

4. Set Docker memory limits:

docker run --memory="512m" --memory-swap="1g" \
  stdiobus/stdiobus:latest

Code block in Bash, 2 lines

Protocol Issues

Invalid JSON Errors

Symptom: Parse errors in logs

Error message:

Parse error: Unexpected token in JSON at position 0

Code block in Text, 1 line

Debugging steps:

1. Validate JSON:

# Test JSON syntax
echo '{"jsonrpc":"2.0","id":"1","method":"test","params":{}}' | jq .
 
# Check for extra whitespace
echo '{"test":true}' | od -c

Code block in Bash, 5 lines

2. Check line endings:

# NDJSON requires \n line endings
# Verify with hexdump
echo '{"test":true}' | hexdump -C

Code block in Bash, 3 lines

3. Test with simple message:

# Minimal valid message
echo '{"jsonrpc":"2.0","id":"1","method":"test","params":{}}' | nc localhost 9000

Code block in Bash, 2 lines

Missing Required Fields

Symptom: JSON-RPC validation errors

Error message:

Error: Missing required field: jsonrpc

Code block in Text, 1 line

Solution:

# Valid JSON-RPC 2.0 request must include:
# - jsonrpc: "2.0"
# - id: string or number (for requests)
# - method: string
# - params: object (optional)
 
# Correct format:
echo '{"jsonrpc":"2.0","id":"1","method":"test","params":{}}' | nc localhost 9000
 
# Incorrect (missing jsonrpc):
echo '{"id":"1","method":"test","params":{}}' | nc localhost 9000

Code block in Bash, 11 lines

Timeout Errors

Symptom: Requests timeout without response

Debugging steps:

1. Check worker is processing:

# Look for worker activity in logs
docker logs <container-name> 2>&1 | tail -f

Code block in Bash, 2 lines

2. Increase timeouts:

{
  "limits": {
    "backpressure_timeout_sec": 120,  // Increase from 60
    "drain_timeout_sec": 60           // Increase from 30
  }
}

Code block in JSON, 6 lines

3. Check for backpressure:

# Look for backpressure warnings in logs
docker logs <container-name> 2>&1 | grep -i "backpressure\|queue full"

Code block in Bash, 2 lines

4. Test with simple worker:

# Use echo worker to isolate issue
# If echo worker works, issue is with specific worker implementation

Code block in Bash, 2 lines

Debugging Commands

Check stdio Bus Status

# Docker container status
docker ps -a | grep stdiobus
 
# Container logs
docker logs <container-name>
 
# Follow logs in real-time
docker logs -f <container-name>
 
# Last 100 lines
docker logs --tail 100 <container-name>
 
# Logs with timestamps
docker logs -t <container-name>

Code block in Bash, 14 lines

Check Worker Status

# List worker processes
ps aux | grep node
 
# Check worker stderr output
docker logs <container-name> 2>&1 | grep "worker-id"
 
# Test worker directly
echo '{"jsonrpc":"2.0","id":"1","method":"test","params":{}}' | \
  node node_modules/@stdiobus/workers-registry/out/dist/index.js echo-worker

Code block in Bash, 9 lines

Network Debugging

# Check port binding
netstat -an | grep 9000
lsof -i :9000
 
# Test TCP connection
nc -zv localhost 9000
telnet localhost 9000
 
# Capture network traffic
tcpdump -i lo -A port 9000
 
# Test with curl (HTTP-like)
curl -X POST http://localhost:9000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"test","params":{}}'

Code block in Bash, 15 lines

Configuration Validation

# Validate JSON syntax
cat config.json | jq .
 
# Check for common issues
jq '.pools[] | select(.instances < 1)' config.json  # Invalid instances
jq '.pools[] | select(.command == null)' config.json  # Missing command
 
# Pretty print configuration
jq . config.json

Code block in Bash, 9 lines

Performance Monitoring

# Docker stats
docker stats <container-name>
 
# Process CPU and memory
top -p $(pgrep stdio_bus)
 
# Network connections
netstat -an | grep 9000 | wc -l
 
# Open file descriptors
lsof -p $(pgrep stdio_bus) | wc -l

Code block in Bash, 11 lines

Error Codes

stdio Bus Error Codes

Code	Message	Description	Solution
1	Configuration error	Invalid configuration file	Validate JSON syntax and required fields
2	Worker spawn error	Failed to start worker process	Check command path and permissions
3	Port binding error	Cannot bind to specified port	Check if port is already in use
4	Worker crash	Worker process crashed	Check worker logs for errors
5	Restart limit exceeded	Worker restarted too many times	Increase restart limits or fix worker issue

JSON-RPC Error Codes

Code	Message	Description	Solution
-32700	Parse error	Invalid JSON	Validate JSON syntax
-32600	Invalid Request	Missing required fields	Include jsonrpc, id, method
-32601	Method not found	Unknown method	Check method name spelling
-32602	Invalid params	Invalid parameters	Validate parameter types and values
-32603	Internal error	Worker internal error	Check worker logs

Worker-Specific Error Codes

Code	Message	Description	Solution
-32000	Server error	Generic worker error	Check worker logs for details
-32001	Session not found	Invalid session ID	Create new session or check session ID
-32002	Agent not found	Invalid agent ID	Check agent ID spelling and availability
-32003	Tool not found	Invalid tool name	List available tools first
-32004	Tool execution error	Tool execution failed	Check tool parameters and logs

Common Error Messages

Command not found

Error:

Error: spawn node ENOENT

Code block in Text, 1 line

Solution:

# Add Node.js to PATH
export PATH="/usr/local/bin:$PATH"
 
# Or use absolute path in configuration
{
  "pools": [{
    "command": "/usr/local/bin/node",
    "args": ["..."]
  }]
}

Code block in Bash, 10 lines

Address already in use

Error:

Error: listen EADDRINUSE: address already in use 0.0.0.0:9000

Code block in Text, 1 line

Solution:

# Find process using port
lsof -i :9000
 
# Kill process
kill -9 <PID>
 
# Or use different port
./stdio_bus --config config.json --tcp 0.0.0.0:9001

Code block in Bash, 8 lines

Too many open files

Error:

Error: EMFILE: too many open files

Code block in Text, 1 line

Solution:

# Check current limit
ulimit -n
 
# Increase limit (temporary)
ulimit -n 4096
 
# Increase limit (permanent)
# Add to /etc/security/limits.conf:
* soft nofile 4096
* hard nofile 8192

Code block in Bash, 10 lines

Worker restart limit exceeded

Error:

Error: Worker restart limit exceeded for pool 'acp-worker'

Code block in Text, 1 line

Solution:

{
  "limits": {
    "max_restarts": 10,        // Increase from 5
    "restart_window_sec": 120  // Increase from 60
  }
}

Code block in JSON, 6 lines

Getting Help

Before Asking for Help

1. Check logs:

stdio Bus logs: docker logs <container-name>
Worker stderr output
System logs

2. Verify configuration:

JSON syntax is valid
Worker names are correct
Paths are correct

3. Test with echo worker:

Isolate issue to specific worker or stdio Bus

4. Check versions:

Node.js version: node --version
Package version: npm list @stdiobus/workers-registry
stdio Bus version: docker inspect stdiobus/stdiobus:latest

Reporting Issues

When reporting issues, include:

1. Environment:

Operating system and version
Node.js version
Package version
stdio Bus version

2. Configuration:

stdio Bus configuration file
Worker configuration
Environment variables

3. Logs:

stdio Bus logs
Worker stderr output
Error messages

4. Steps to reproduce:

Exact commands run
Expected behavior
Actual behavior

Support Channels

GitHub Issues: github.com/stdiobus/workers-registry/issues
GitHub Discussions: github.com/stdiobus/workers-registry/discussions
Documentation: stdiobus.com

Next Steps

Configuration - Review configuration options
Integration - Integration patterns and examples
API Reference - Complete API documentation
Installation - Installation guide

stdio Bus

Troubleshooting

Worker Registry LauncherAvailable worker types and their specific implementations

Overview

Installation Issues

Node.js Version Mismatch

Permission Errors

Package Not Found

Build Errors

Runtime Issues

Worker Not Starting

Worker Crashes

Connection Refused

Session Affinity Not Working

Memory Issues

Protocol Issues

Invalid JSON Errors

Missing Required Fields

Timeout Errors

Debugging Commands

Check stdio Bus Status

Check Worker Status

Network Debugging

Configuration Validation

Performance Monitoring

Error Codes

stdio Bus Error Codes

JSON-RPC Error Codes

Worker-Specific Error Codes

Common Error Messages

Command not found

Address already in use

Too many open files

Worker restart limit exceeded

Getting Help

Before Asking for Help

Reporting Issues

Support Channels

Next Steps

Resources