Debugging Guide

Comprehensive debugging strategies for Orchestre projects.

Debug Mode

Enable Debug Output

# Set environment variable
export ORCHESTRE_DEBUG=true
export ORCHESTRE_LOG_LEVEL=debug

# Run with debug
node /path/to/orchestre/dist/server.js

Debug Information

When debug mode is enabled:

• Detailed MCP communication logs
• Tool execution timing
• API call details
• Error stack traces

Common Issues

MCP Connection Problems

Symptoms: Tools don't appear in Claude Code

Debug Steps:

1. Check server path in MCP config
2. Verify dist/server.js exists (not src/)
3. Check for error messages in Claude Code
4. Ensure API keys are set

# Verify build
ls -la dist/server.js

# Test server directly
node dist/server.js

Tool Execution Errors

Symptoms: Tools fail with errors

Debug Steps:

1. Enable debug mode
2. Check error details in response
3. Verify API keys are valid
4. Check rate limits

# Test API keys
env | grep "_API_KEY"

# Check specific tool
/orchestrate "Test analyze project tool"

Template Issues

Symptoms: Template commands not working

Debug Steps:

1. Verify template was initialized correctly
2. Check template.json exists
3. Ensure commands are installed
4. Review command files

# Check template
cat template.json

# List available commands
ls templates/*/commands/

Debugging Tools

Log Analysis

# Filter debug logs
export ORCHESTRE_DEBUG=true 2>&1 | grep "ERROR"

# Save logs to file
export ORCHESTRE_DEBUG=true 2>&1 | tee debug.log

State Inspection

# Check project state
/status

# Discover context
/discover-context

# Review memory files
find . -name "CLAUDE.md" -type f

Performance Profiling

# Time operations
export ORCHESTRE_DEBUG=true
export ORCHESTRE_LOG_LEVEL=verbose

# Monitor resource usage
top -p $(pgrep -f orchestre)

Tool-Specific Debugging

analyzeProject

Common issues:

• Requirements too vague
• Gemini API errors
• Timeout on large projects

Debug:

# Test with simple requirements
/orchestrate "Analyze simple TODO app requirements"

# Check Gemini API
curl -H "x-goog-api-key: $GEMINI_API_KEY" \
  https://generativelanguage.googleapis.com/v1/models

multiLlmReview

Common issues:

• Model disagreements
• Token limits exceeded
• Missing file content

Debug:

# Test with small file
echo "console.log('test');" > test.js
/review test.js

# Check model availability
/orchestrate "List available review models"

initializeProject

Common issues:

• Template not found
• Permission denied
• Path already exists

Debug:

# List templates
ls templates/

# Check permissions
ls -la /target/directory/

# Test with temp directory
/create "test-app" using cloudflare-hono in /tmp

Environment Debugging

API Key Issues

# Check all keys
env | grep -E "(ANTHROPIC|OPENAI|GEMINI)_API_KEY"

# Test each provider
/orchestrate "Test Anthropic API"
/orchestrate "Test OpenAI API"
/orchestrate "Test Gemini API"

Path Issues

# Check working directory
pwd

# Verify Orchestre path
which orchestre

# Check Node version
node --version  # Should be 18+

Error Messages

Common Errors

"Template not found"

• Check template name spelling
• Verify template exists in templates/
• Use exact template name (case-sensitive)

"API key missing"

• Set required environment variables
• Check .env file is loaded
• Verify key format is correct

"Rate limit exceeded"

• Wait before retrying
• Reduce parallel operations
• Check API quotas

"File not found"

• Use absolute paths
• Check file permissions
• Verify working directory

Advanced Debugging

Source Maps

# Build with source maps
npm run build -- --sourceMap

# Better stack traces
node --enable-source-maps dist/server.js

Remote Debugging

# Node.js debugging
node --inspect dist/server.js

# Connect debugger to port 9229

Memory Leaks

# Heap snapshots
node --inspect dist/server.js
# Use Chrome DevTools Memory Profiler

# Monitor memory
node --expose-gc dist/server.js

Reporting Issues

When reporting bugs, include:

1. Environment:

   node --version
   npm --version
   echo $OSTYPE

2. Error Details:

   • Full error message
   • Stack trace
   • Debug logs

3. Reproduction Steps:

   • Minimal example
   • Expected behavior
   • Actual behavior

4. Configuration:

   • MCP config (without keys)
   • Template used
   • Command executed

See Also

• Troubleshooting Guide
• Error Reference
• FAQ