Common Issues

Installation & Startup

"npm ERR! Cannot find module"

cd orchestrator
rm -rf node_modules package-lock.json
npm install

"orchestrator_config.json is missing docsPath"

Create/update orchestrator_config.json:

{
  "docsPath": "./openclaw-docs",
  "logsDir": "./logs",
  "stateFile": "./orchestrator/data/orchestrator-state.json"
}

System doesn't start

Check logs:

npm start 2>&1 | head -50

Look for:

• File not found errors
• JSON parse errors
• Permission denied

"logs directory doesn't exist"

This is normal. The system creates it. Verify:

ls -la logs/
cat logs/orchestrator.log

---

Runtime Issues

No logs appearing

Check environment:

# Verify config loaded
cat orchestrator_config.json | jq .

# Check log directory writable
touch logs/test.txt && rm logs/test.txt

# Restart
npm start

Heartbeat not appearing

Check state:

curl -fsS -H "Authorization: Bearer $API_KEY" \
  http://127.0.0.1:3312/api/dashboard/overview | jq '.health.lastHeartbeatAt'

If null or old, system may have crashed:

npm start 2>&1 | tail -20

Tasks not processing

Check queue and concurrency:

# View last 5 visible tasks
curl -fsS -H "Authorization: Bearer $API_KEY" \
  "http://127.0.0.1:3312/api/tasks/runs?limit=5" | jq '.runs'

# Check internal maintenance runs too when needed
curl -fsS -H "Authorization: Bearer $API_KEY" \
  "http://127.0.0.1:3312/api/tasks/runs?limit=10&includeInternal=true" | jq '.runs'

---

Agent Issues

"Agent spawn failed"

Check agent template exists:

ls -la agents/doc-specialist/src/index.ts
ls -la agents/reddit-helper/src/index.ts

"No handler for task type"

Typo in task type. Check Task Types for valid names.

---

See Debugging for deeper diagnosis.