Troubleshooting

Troubleshooting

Common issues and solutions for Agentwise development and deployment.

Quick Diagnostics

System Health Check

# Run comprehensive system check
npm run system:health

# Check agent status
npm run agents:status

# Validate configuration
npm run config:validate

# Test MCP servers
npm run mcp:test-all

# Monitor system resources
npm run monitor:resources

Common Issues

Installation and Setup Issues

Node.js Version Compatibility

Problem: Agentwise fails to start with Node.js version errors

Symptoms:

• Error: Unsupported Node.js version
• Module import/export errors
• Package installation failures

Solution:

# Check Node.js version
node --version  # Should be 18.0.0 or higher

# Update Node.js using nvm
nvm install 18
nvm use 18

# Or update npm
npm install -g npm@latest

# Clean install dependencies
rm -rf node_modules package-lock.json
npm install

MCP Server Discovery Issues

Problem: MCP servers not found or failing to connect

Symptoms:

• MCP server not found: filesystem
• Connection timeout errors
• Tool discovery failures

Solution:

# Install missing MCP servers
npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-github

# Check server installation
which npx  # Should return path to npx

# Test server directly
npx -y @modelcontextprotocol/server-filesystem --help

# Validate MCP configuration
npm run mcp:validate-config

Agent Issues

Agent Not Responding

Problem: Agents appear stuck or unresponsive

Symptoms:

• Tasks remain in "in_progress" state
• Agent shows as "unhealthy"
• No progress updates

Diagnostic Steps:

# Check agent status
npm run agents:status

# View agent logs
npm run agents:logs <agent-name>

# Monitor agent resources
npm run agents:monitor <agent-name>

Solutions:

# Restart specific agent
npm run agent:restart <agent-name>

# Reset agent state
npm run agent:reset <agent-name>

# Increase agent timeout
# Edit .claude/config.json:
{
  "agents": {
    "timeout": 600  // Increase from 300 to 600 seconds
  }
}

# Clear agent cache
npm run agent:clear-cache <agent-name>

Agent Task Assignment Failures

Problem: Tasks not being assigned to appropriate agents

Symptoms:

• Tasks queued but never started
• Wrong agent assigned to task
• Capability mismatch errors

Solution:

# Check agent capabilities
npm run agents:capabilities

# View task queue
npm run tasks:queue

# Force task reassignment
npm run task:reassign <task-id> <agent-name>

# Update agent definitions
# Check .claude/agents/ directory for agent configs

Token and Budget Issues

Token Budget Exhaustion

Problem: Tasks failing due to insufficient token budget

Symptoms:

• Insufficient token budget errors
• Tasks terminated early
• Quality degradation

Solution:

# Check current token usage
npm run tokens:usage

# Increase token budget
# Edit .claude/config.json:
{
  "tokens": {
    "budget": 200000  // Increase budget
  }
}

# Enable aggressive optimization
{
  "tokens": {
    "optimization": "aggressive"
  }
}

# Clear token usage cache
npm run tokens:reset

Token Optimization Not Working

Problem: Expected token savings not achieved

Symptoms:

• High token usage despite optimization
• No compression occurring
• Templates not being reused

Diagnostic:

# Check optimization status
npm run optimization:status

# View optimization metrics
npm run optimization:metrics

# Test compression
npm run optimization:test-compression

Solution:

# Enable optimization
{
  "optimization": {
    "enabled": true,
    "compression": true,
    "template_reuse": true,
    "context_sharing": true
  }
}

# Clear optimization cache
npm run optimization:clear-cache

# Restart with optimization
npm run start --optimize

Performance Issues

Slow Task Completion

Problem: Tasks taking much longer than expected

Symptoms:

• Task completion times > 10 minutes
• System appears slow overall
• User complaints about performance

Diagnostic:

# Profile system performance
npm run profile:system

# Check resource usage
npm run monitor:resources

# Analyze task performance
npm run tasks:analyze-performance

Solutions:

# Increase agent concurrency
{
  "agents": {
    "maxConcurrent": 5  // Increase from 3
  }
}

# Enable caching
{
  "caching": {
    "enabled": true,
    "strategy": "aggressive"
  }
}

# Optimize token usage
{
  "tokens": {
    "optimization": "aggressive"
  }
}

# Clear all caches
npm run cache:clear-all

High Memory Usage

Problem: System consuming excessive memory

Symptoms:

• Out of memory errors
• System slowdown
• Process crashes

Solution:

# Monitor memory usage
npm run monitor:memory

# Limit concurrent operations
{
  "performance": {
    "maxConcurrentTasks": 3,
    "memoryLimit": "2GB"
  }
}

# Enable garbage collection optimization
npm run start --optimize-memory

# Clear memory caches
npm run memory:clear-caches

Project Generation Issues

Project Creation Failures

Problem: Project creation fails or produces incomplete results

Symptoms:

• Project creation failed errors
• Missing files or directories
• Malformed code generation

Diagnostic:

# Check project generation logs
npm run projects:logs <project-id>

# Validate project requirements
npm run projects:validate-requirements

# Test with minimal project
npm run projects:create-test

Solutions:

# Use specific project template
agentwise create --template web-application

# Reduce project complexity
# Simplify requirements in project specification

# Check available disk space
df -h

# Increase generation timeout
{
  "projects": {
    "timeout": 1800  // 30 minutes
  }
}

Code Quality Issues

Problem: Generated code has quality problems

Symptoms:

• Syntax errors in generated code
• Missing dependencies
• Poor code structure

Solution:

# Enable quality checks
{
  "quality": {
    "linting": true,
    "validation": true,
    "formatting": true
  }
}

# Use higher quality profile
agentwise create --quality production

# Review and fix generated code
npm run code:review <project-path>

API and Integration Issues

API Connection Failures

Problem: Cannot connect to Agentwise API

Symptoms:

• Connection refused errors
• API timeouts
• Authentication failures

Solution:

# Check API server status
curl http://localhost:3001/api/v1/health

# Start API server
npm run api:start

# Check authentication
export AGENTWISE_API_KEY="your-api-key"

# Test API connectivity
npm run api:test

WebSocket Connection Issues

Problem: Real-time updates not working

Symptoms:

• No progress updates in dashboard
• WebSocket connection errors
• Stale data in UI

Solution:

# Test WebSocket connection
npm run ws:test

# Check firewall/proxy settings
# Ensure port 3001 is accessible

# Restart with WebSocket debugging
npm run start --debug-websocket

Error Code Reference

System Errors

Error Code	Description	Solution
AGENT_001	Agent initialization failed	Check agent configuration, restart agent
AGENT_002	Agent timeout	Increase timeout, check agent resources
AGENT_003	Agent capability mismatch	Review task requirements, update agent
TOKEN_001	Insufficient token budget	Increase budget or enable optimization
TOKEN_002	Token optimization failed	Check optimization configuration
MCP_001	MCP server not found	Install server, check configuration
MCP_002	MCP connection timeout	Check server health, increase timeout
PROJ_001	Project creation failed	Check requirements, increase resources
PROJ_002	File generation error	Check permissions, disk space

Recovery Procedures

Complete System Reset

# Stop all services
npm run stop

# Clear all caches
npm run cache:clear-all

# Reset configuration
npm run config:reset

# Reinstall dependencies
rm -rf node_modules
npm install

# Restart system
npm run start

Agent Pool Reset

# Stop all agents
npm run agents:stop

# Clear agent state
npm run agents:clear-state

# Reset agent configurations
npm run agents:reset-config

# Restart agents
npm run agents:start

Token Budget Reset

# Clear token usage history
npm run tokens:clear-history

# Reset optimization cache
npm run optimization:reset

# Update token configuration
npm run config:update-tokens

Diagnostic Commands

System Diagnostics

# Comprehensive system check
npm run system:diagnose

# Generate diagnostic report
npm run system:report > diagnostic_report.txt

# Check system dependencies
npm run system:check-deps

# Validate environment
npm run system:validate-env

Agent Diagnostics

# Test all agents
npm run agents:test-all

# Check agent capabilities
npm run agents:capabilities

# Monitor agent performance
npm run agents:benchmark

# Agent communication test
npm run agents:test-communication

Performance Diagnostics

# Performance profiling
npm run profile:cpu
npm run profile:memory
npm run profile:tokens

# Load testing
npm run test:load

# Benchmark comparison
npm run benchmark:compare

Prevention Strategies

Monitoring Setup

# Enable system monitoring
npm run monitoring:enable

# Set up alerts
npm run alerts:configure

# Dashboard setup
npm run dashboard:start

Regular Maintenance

# Weekly maintenance script
#!/bin/bash
npm run cache:cleanup
npm run logs:rotate
npm run agents:health-check
npm run optimization:tune
npm run system:update-deps

Backup and Recovery

# Backup configuration
npm run backup:config

# Backup project data
npm run backup:projects

# Test recovery procedures
npm run test:recovery

Getting Help

Support Channels

• GitHub Issues: Report bugs and feature requests
• GitHub Discussions: Community Q&A and ideas
• Discord: Real-time chat support (@vibecodingwithphil)
• Documentation: Comprehensive guides and references

Before Contacting Support

1. Check this troubleshooting guide
2. Run system diagnostics: npm run system:diagnose
3. Check existing issues: Search GitHub issues
4. Gather information:
   • Agentwise version
   • Node.js version
   • Operating system
   • Error logs
   • Steps to reproduce

Providing Effective Bug Reports

Include:

• Clear description of the problem
• Steps to reproduce the issue
• Expected vs actual behavior
• System information and logs
• Configuration files (sanitized)
• Screenshots if applicable

---

For more information, see Configuration, Performance Tuning, or FAQ.