Common Issues and Solutions

This guide covers the most common issues you might encounter with Orchestre and how to resolve them.

MCP Server Issues

Issue: "MCP tool not found" Error

Symptoms:

• Commands return "MCP tool not found"
• Orchestre commands not recognized
• Claude Code doesn't show Orchestre tools

Solutions:

1. Restart Claude Code

   • Completely quit Claude Code
   • Start it again
   • MCP servers load on startup

2. Check Configuration

   // ~/Library/Application Support/Claude/claude_desktop_config.json
   {
     "mcpServers": {
       "orchestre": {
         "command": "node",
         "args": ["/absolute/path/to/orchestre/dist/server.js"],
         "env": {
           "GEMINI_API_KEY": "your-key",
           "OPENAI_API_KEY": "your-key"
         }
       }
     }
   }

3. Verify Build

   cd /path/to/orchestre
   npm run build
   # Should create dist/server.js

4. Check Logs

   # MacOS
   tail -f ~/Library/Logs/Claude/mcp.log
   
   # Look for Orchestre-related errors

Issue: MCP Server Fails to Start

Symptoms:

• Error in Claude Code logs
• "Failed to start MCP server" message

Solutions:

1. Use Absolute Paths

   // ❌ Wrong - relative path
   "args": ["./dist/server.js"]
   
   // ✅ Correct - absolute path
   "args": ["/Users/username/orchestre/dist/server.js"]

2. Check Node Version

   node --version
   # Should be 18.0.0 or higher

3. Verify Dependencies

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

---

API Key Issues

Issue: Gemini API Key Not Working

Symptoms:

• /orchestre:orchestrate (MCP) command fails
• "Invalid API key" errors
• Analysis features not working

Solutions:

1. Verify API Key

   • Go to Google AI Studio
   • Create new API key if needed
   • Ensure key has correct permissions

2. Check Configuration

   "env": {
     "GEMINI_API_KEY": "your-actual-key-here"
   }

3. Test API Key

   curl -H "Content-Type: application/json" \
        -H "x-goog-api-key: YOUR_API_KEY" \
        "https://generativelanguage.googleapis.com/v1/models"

Issue: OpenAI API Key Not Working

Symptoms:

• /orchestre:review (MCP) command fails
• Multi-LLM features not working

Solutions:

1. Check API Key Format

   • Should start with sk-
   • No extra spaces or quotes

2. Verify Quota

   • Check OpenAI dashboard for usage
   • Ensure billing is set up
   • Check rate limits

---

Command Execution Issues

Issue: Commands Not Working in Project

Symptoms:

• Commands work in some directories but not others
• "Project not found" errors
• Commands don't recognize project context

Solutions:

1. Run from Project Root

   cd /path/to/your/project
   /orchestre:orchestrate (MCP) "your requirements"

2. Check .orchestre Directory

   ls -la .orchestre/
   # Should exist with config files

3. Initialize Project

   /orchestre:create (MCP) my-project template-name
   # Or for existing projects:
   /orchestre:orchestrate (MCP) "Initialize Orchestre in existing project"

Issue: Commands Hanging or Timing Out

Symptoms:

• Commands take forever
• No output after running command
• Claude Code becomes unresponsive

Solutions:

1. Check Network

   • Ensure internet connection
   • Check firewall settings
   • Verify API endpoints accessible

2. Reduce Complexity

   # Instead of:
   /orchestre:orchestrate (MCP) "Build complete e-commerce platform"
   
   # Try:
   /orchestre:orchestrate (MCP) "Plan user authentication system"

3. Check API Status

   • Google AI Status
   • OpenAI Status

---

Template Issues

Issue: Template Not Found

Symptoms:

• /orchestre:create (MCP) fails with "template not found"
• Can't use specific template

Solutions:

1. Check Template Name

   # Correct template names:
   makerkit-nextjs
   cloudflare-hono
   react-native-expo

2. Verify Template Files

   ls templates/
   # Should show template directories

Issue: MakerKit-Specific Tasks Not Working

Symptoms:

• MakerKit-specific features fail
• Stripe setup or other template-specific tasks not working

Solutions:

1. Ensure MakerKit Template

   # Check template.json
   cat .orchestre/config.yaml
   # Should show template: makerkit-nextjs

2. Reinitialize if Needed

   /orchestre:create (MCP) new-project makerkit-nextjs

---

Build and Development Issues

Issue: TypeScript Errors

Symptoms:

• Build fails with type errors
• Red squiggles in editor

Solutions:

1. Install Dependencies

   npm install
   npm install --save-dev @types/node

2. Check tsconfig.json

   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "NodeNext",
       "moduleResolution": "NodeNext"
     }
   }

Issue: Module Not Found Errors

Symptoms:

• Cannot find module errors
• Import paths not working

Solutions:

1. Check File Extensions

   // ❌ Wrong - missing extension
   import { tool } from './tool'
   
   // ✅ Correct - with extension
   import { tool } from './tool.js'

2. Verify Build Output

   npm run build
   ls dist/
   # Should contain .js files

---

Performance Issues

Issue: Slow Command Execution

Symptoms:

• Commands take long time
• High memory usage
• System becomes sluggish

Solutions:

1. Break Down Tasks

   # Instead of one large task
   /orchestre:orchestrate (MCP)
   # Then provide: "Break down large feature into smaller tasks"

2. Use Specific Commands

   # More specific = faster
   /orchestre:execute-task (MCP) "Add user login endpoint"
   # vs
   /orchestre:execute-task (MCP) "Add authentication"

3. Check System Resources

   • Close unnecessary applications
   • Check available RAM
   • Monitor CPU usage

---

Integration Issues

Issue: Git Integration Problems

Symptoms:

• Can't commit changes
• Git commands fail
• Merge conflicts

Solutions:

1. Check Git Status

   git status
   git config --list

2. Use Separate Branches

   git checkout -b feature/new-feature
   /orchestre:execute-task (MCP)
   # Then provide: "Implement feature"
   git add .
   git commit -m "Add feature"

Issue: Database Connection Errors

Symptoms:

• Database queries fail
• Connection timeout errors

Solutions:

1. Check Connection String

   # In .env file
   DATABASE_URL=postgresql://user:pass@localhost:5432/db

2. Verify Database Running

   # PostgreSQL
   psql -U postgres -c "SELECT 1"
   
   # MySQL
   mysql -u root -p -e "SELECT 1"

---

Error Messages

"Context length exceeded"

Solution: Break down your request into smaller parts

"Rate limit exceeded"

Solution: Wait a few minutes, use different API key, or upgrade plan

"Invalid project structure"

Solution: Ensure you're in a valid Orchestre project directory

"Template command not found"

Solution: Verify you're using the correct template

---

Debug Mode

Enable debug output for troubleshooting:

# In your shell
export ORCHESTRE_DEBUG=true

# Then run commands
/orchestre:orchestrate (MCP)
# Then provide: "your task"

---

Getting Help

If these solutions don't resolve your issue:

1. Check Documentation

   • Review relevant guides
   • Check command reference
   • Look for examples

2. Search Issues

   • GitHub Issues
   • Look for similar problems
   • Check closed issues too

3. Create Issue

   • Provide error messages
   • Include configuration
   • Describe steps to reproduce
   • Mention your environment

4. Community Support

   • Discussions
   • Ask questions
   • Share solutions

---

Prevention Tips

1. Keep Updated

   git pull origin main
   npm install
   npm run build

2. Regular Backups

   • Commit changes frequently
   • Push to remote repository
   • Document custom configurations

3. Monitor Resources

   • Check API quotas
   • Monitor rate limits
   • Track usage patterns

4. Test Changes

   • Use development branch
   • Test in isolated environment
   • Validate before production

---

Quick Fixes

# Restart everything
pkill "Claude Code" && open -a "Claude Code"

# Rebuild Orchestre
cd /path/to/orchestre && npm run build

# Clear cache
rm -rf node_modules && npm install

# Reset configuration
/orchestre:orchestrate (MCP)
# Then provide: "Reset and reinitialize project configuration"