Troubleshooting Guide

This guide helps you resolve common issues with the Sigao CLI Workpackage Automation system.

Installation Issues

npm Installation Fails

npm ERR! code EACCES
npm ERR! permission denied

Solutions:

1. Fix npm permissions (Recommended):

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

2. Use npx instead of global install:

   npx @sigaostudios/sigao-cli work package.json
   

3. Use a Node version manager:

   # Install nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   
   # Install Node.js
   nvm install 18
   nvm use 18
   

Module Not Found

Error: Cannot find module '@sigaostudios/sigao-cli'

Solutions:

1. Verify installation:

   npm list -g @sigaostudios/sigao-cli
   

2. Clear npm cache:

   npm cache clean --force
   npm install -g @sigaostudios/sigao-cli
   

3. Check NODE_PATH:

   echo $NODE_PATH
   export NODE_PATH=$(npm root -g)
   

Claude CLI Problems

Claude Command Not Found

bash: claude: command not found

Solutions:

1. Verify Claude CLI installation:

   # Check if installed
   which claude
   
   # If not found, reinstall
   npm install -g @anthropic/claude-cli
   

2. Add to PATH manually:

   # Find Claude location
   find ~ -name "claude" -type f 2>/dev/null
   
   # Add to PATH (adjust path as needed)
   export PATH="$PATH:/usr/local/bin"
   

3. Use direct path:

   # Find and use full path
   /usr/local/bin/claude --version
   

Authentication Failed

Error: Authentication required. Please run 'claude auth login'

Solutions:

1. Login to Claude:

   claude auth login
   # Follow prompts to enter API key
   

2. Check API key:

   # Verify key is set
   claude auth status
   

3. Set environment variable:

   export ANTHROPIC_API_KEY="your-api-key-here"
   

Rate Limit Errors

Error: Rate limit exceeded. Please wait before retrying.

Solutions:

1. Add delays between tasks:

   "uow_context": {
     "execution_delay": 2000  // 2 second delay
   }
   

2. Use retry with backoff:

   sigao work package.json --retry-delay 5000
   

Workpackage Validation Errors

Invalid JSON Syntax

SyntaxError: Unexpected token } in JSON at position 245

Solutions:

1. Validate JSON syntax:

   # Use jq to validate
   jq . my-workpackage.json
   
   # Or use Node.js
   node -e "console.log(JSON.parse(require('fs').readFileSync('my-workpackage.json', 'utf8')))"
   

2. Common JSON issues:
   • Missing commas between elements
   • Trailing commas (not allowed in JSON)
   • Unmatched brackets or braces
   • Unescaped quotes in strings
3. Use a JSON linter:
   • VS Code: Format document (Shift+Alt+F)
   • Online: JSONLint

Schema Validation Failed

Validation Error: Workpackage missing required field: 'id'

Solutions:

1. Check required fields:

   {
     "id": "WP-01-EXAMPLE",        // Required: WP-XX-NAME format
     "title": "Example Package",    // Required
     "depends_on": [],             // Required (can be empty)
     "tasks": [...],               // Required (at least one task)
     "deliverables": [...],        // Required
     "agent": "claude",            // Required
     "status": "ready"             // Required
   }
   

2. Validate ID format:
   • Must match pattern: WP-XX-NAME
   • Examples: WP-01-SETUP, WP-02-API, WP-10-DEPLOY
3. Use the validator:

   node -e "
   import('./src/modules/workpackage/validator.js').then(m => {
     const v = new m.WorkpackageValidator();
     const data = JSON.parse(require('fs').readFileSync('package.json', 'utf8'));
     const result = v.validate(data);
     console.log(result.valid ? 'Valid' : result.errors);
   })
   "
   

Missing Dependencies

Error: Dependency 'WP-01-SETUP' not found

Solutions:

1. Check dependency exists:
   • Ensure all referenced IDs exist in the same file
   • Dependencies must be defined before they're referenced
2. Fix circular dependencies:
   ❌ Circular dependency✅ Correct

   {
     "id": "WP-01-A",
     "depends_on": ["WP-02-B"]
   },
   {
     "id": "WP-02-B", 
     "depends_on": ["WP-01-A"]
   }
   

Execution Failures

Task Execution Timeout

Error: Task execution timed out after 300000ms

Solutions:

1. Increase timeout:

   sigao work package.json --timeout 600000  # 10 minutes
   

2. Break down large tasks:
   ❌ Too large✅ Better

   {
     "task": "Create entire application"
   }
   

Out of Memory

FATAL ERROR: JavaScript heap out of memory

Solutions:

1. Increase Node.js memory:

   NODE_OPTIONS='--max-old-space-size=4096' sigao work package.json
   

2. Process workpackages individually:

   # Instead of all at once
   sigao work all-packages.json
   
   # Process one by one
   sigao work setup.json
   sigao work api.json
   

File Permission Errors

Error: EACCES: permission denied, open '/usr/local/file.js'

Solutions:

1. Check directory permissions:

   ls -la directory/
   chmod 755 directory/
   

2. Run in user directory:

   cd ~/my-project
   sigao work package.json
   

Test Failures

Test Command Not Found

Error: Command 'npm test' exited with code 1
/bin/sh: npm: command not found

Solutions:

1. Use full paths:

   {
     "test": "/usr/local/bin/npm test"
   }
   

2. Check command availability:

   which npm
   which node
   

3. Use shell built-ins:

   {
     "test": "test -f file.js && echo 'exists' || exit 1"
   }
   

Test Assertions Fail

✓ Task completed
✗ Acceptance test failed
Expected file to contain 'export default'

Solutions:

1. Debug test command:

   # Run test manually
   grep -q 'export default' file.js
   echo $?  # Check exit code
   

2. Make tests more flexible:
   ❌ Too strict✅ More flexible

   {
     "test": "grep -q 'export default Config' config.js"
   }
   

Performance Issues

Slow Execution

Symptoms:

• Tasks take longer than expected
• High memory usage
• System becomes unresponsive

Solutions:

1. Monitor resource usage:

   # Run with performance monitoring
   sigao work package.json --log-level debug
   

2. Optimize workpackage structure:
   • Run independent tasks in parallel
   • Reduce context size
   • Minimize file I/O operations
3. System optimizations:

   # Close unnecessary applications
   # Check disk space
   df -h
   
   # Check system resources
   top
   

Environment-Specific Problems

Windows Issues

Path Separators:

{
  "test": "test -f src/file.js"
}

{
  "test": "node -e \"require('fs').existsSync('src/file.js') || process.exit(1)\""
}

Line Endings:

# Configure Git for Windows
git config --global core.autocrlf true

macOS Issues

Homebrew Conflicts:

# If Node/npm installed via Homebrew conflicts
brew unlink node
brew link node --force

Linux Issues

SELinux/AppArmor:

# Check SELinux status
sestatus

# Temporarily disable for testing
sudo setenforce 0

Getting Additional Help

Debug Mode

Enable comprehensive logging:

sigao work package.json --log-level debug > debug.log 2>&1

Diagnostic Information

Collect system information:

# Create diagnostic report
cat > diagnostic.txt << EOF
Node Version: $(node --version)
NPM Version: $(npm --version)
OS: $(uname -a)
Claude CLI: $(claude --version 2>&1)
Sigao CLI: $(sigao --version 2>&1)
Working Directory: $(pwd)
EOF

Common Log Locations

Check these files for more details:

.sigao/
├── workpackage/
│   └── run-*/
│       ├── logs/
│       │   ├── execution.log    # Full execution log
│       │   ├── errors.log       # Error details
│       │   └── debug.log        # Debug information
│       └── status.json          # Execution status

Reporting Issues

When reporting issues, include:

1. The exact error message
2. Your workpackage JSON (sanitized)
3. Output of diagnostic commands
4. Steps to reproduce

Community Resources

• GitHub Issues: Report bugs and request features
• Discord: Real-time help from the community
• Stack Overflow: Tag questions with sigao-cli
• Documentation: Always check the latest docs

Emergency Fixes

If all else fails:

1. Clean reinstall:

   npm uninstall -g @sigaostudios/sigao-cli
   npm cache clean --force
   npm install -g @sigaostudios/sigao-cli
   

2. Reset configuration:

   rm -rf ~/.sigao
   rm -rf .sigao
   

3. Use Docker:

   docker run -v $(pwd):/workspace sigao/cli work package.json