Troubleshooting Guide

Common issues and solutions when working with Orchestre.

Quick Solutions

Installation Issues

MCP Server not connecting to Claude Code

# Check if Orchestre is built
npm run build

# Verify MCP configuration in Claude Code settings
# Should point to dist/server.js, not src/server.ts

Missing API Keys

# Orchestre requires at least one LLM provider API key
export ANTHROPIC_API_KEY="your-key"
# OR
export OPENAI_API_KEY="your-key"  
# OR
export GEMINI_API_KEY="your-key"

Tool Errors

"Template not found" error

• Valid templates: makerkit-nextjs, cloudflare-hono, react-native-expo
• Check spelling and case (all lowercase)

Analysis timing out

• Simplify requirements to be more specific
• Break complex projects into phases
• Check Gemini API key is valid

Review consensus failed

• This happens when models strongly disagree
• Review the specific findings from each model
• Consider manual review for critical code

Memory Management

CLAUDE.md files not updating

• Orchestre uses distributed CLAUDE.md files for project memory
• Check file permissions
• Ensure you're in the correct directory
• Each feature should have its own CLAUDE.md

Missing project context

• Look for CLAUDE.md files throughout your project
• These contain architectural decisions and context
• Run /discover-context to find existing documentation
• Use /document-feature to create new documentation

Command Issues

Command not recognized

• Template-specific commands only work with that template
• Check available commands with /status
• Core commands work with all projects

Parallel commands not working

• Ensure /setup-parallel was run first
• Check that tasks are properly distributed
• Verify no resource conflicts

Debug Mode

Enable detailed logging:

# Set debug environment variable
export ORCHESTRE_DEBUG=true

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

Common Scenarios

Starting Fresh

If things aren't working as expected:

1. Check your environment:

   # Verify API keys are set
   env | grep -E "(ANTHROPIC|OPENAI|GEMINI)_API_KEY"
   
   # Check Node.js version (requires 18+)
   node --version

2. Rebuild Orchestre:

   cd /path/to/orchestre
   npm install
   npm run build

3. Verify MCP configuration points to built files:

   {
     "mcpServers": {
       "orchestre": {
         "command": "node",
         "args": ["/path/to/orchestre/dist/server.js"]
       }
     }
   }

Performance Issues

Slow responses

• Check API rate limits
• Reduce parallel operations
• Use simpler prompts for faster iteration

Memory usage

• Orchestre loads templates on demand
• Large projects may need more memory
• Consider breaking into smaller modules

Integration Problems

MCP tools not appearing

• Restart Claude Code after configuration
• Check server.js is built (not TypeScript)
• Verify path in MCP configuration

Environment variables not loading

• Pass them directly in MCP config
• Or use a .env file with proper loading

Getting Help

Check Documentation

• Installation Guide
• Configuration Reference
• Command Reference

Debug Information

When reporting issues, include:

1. Orchestre version
2. Error messages
3. Debug output
4. Your configuration (without API keys)

Community Support

• GitHub Issues
• GitHub Discussions

See Also

• FAQ
• Error Reference
• Debugging Guide