Error Reference

Comprehensive guide to error codes, messages, and handling in Orchestre.

Error Categories

MCP Protocol Errors

Standard JSON-RPC 2.0 error codes used by MCP:

Code	Constant	Description
-32700	PARSE_ERROR	Invalid JSON received
-32600	INVALID_REQUEST	JSON is valid but request object is invalid
-32601	METHOD_NOT_FOUND	Requested method does not exist
-32602	INVALID_PARAMS	Invalid method parameters
-32603	INTERNAL_ERROR	Internal server error

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "field": "requirements",
      "issue": "String too short (minimum 10 characters)"
    }
  }
}

Tool-Specific Errors

Initialization Errors

Code	Description	Resolution
TEMPLATE_NOT_FOUND	Specified template doesn't exist	Use valid template name
PROJECT_EXISTS	Project directory already exists	Choose different name or path
INVALID_PROJECT_NAME	Project name contains invalid characters	Use lowercase letters, numbers, hyphens
PERMISSION_DENIED	Cannot create project directory	Check file permissions

Example:

{
  error: "Template not found",
  code: "TEMPLATE_NOT_FOUND",
  availableTemplates: ["makerkit-nextjs", "cloudflare-hono", "react-native-expo"],
  suggestion: "Use one of the available templates"
}

Analysis Errors

Code	Description	Resolution
REQUIREMENTS_TOO_VAGUE	Requirements lack detail	Provide specific features and constraints
ANALYSIS_TIMEOUT	Analysis took too long	Simplify requirements or retry
API_KEY_MISSING	Gemini API key not configured	Set GEMINI_API_KEY environment variable
RATE_LIMIT_EXCEEDED	Too many API requests	Wait before retrying

Example:

{
  error: "Requirements too vague",
  code: "REQUIREMENTS_TOO_VAGUE",
  suggestion: "Include specific features like 'user authentication', 'payment processing', or 'admin dashboard'",
  example: "Build a SaaS platform with user registration, subscription billing, and team management"
}

Planning Errors

Code	Description	Resolution
INVALID_ANALYSIS	Analysis data is malformed	Re-run project analysis
CIRCULAR_DEPENDENCY	Tasks have circular dependencies	Review task dependencies
RESOURCE_CONFLICT	Parallel tasks conflict	Adjust parallelization settings
PLAN_GENERATION_FAILED	Could not generate valid plan	Check analysis results

Review Errors

Code	Description	Resolution
NO_FILES_PROVIDED	No files to review	Provide at least one file
FILE_NOT_FOUND	Specified file doesn't exist	Check file paths
REVIEW_CONSENSUS_FAILED	Models strongly disagree	Manual review recommended
MODEL_UNAVAILABLE	Review model not accessible	Check API keys and model availability

Research Errors

Code	Description	Resolution
TOPIC_TOO_BROAD	Research topic needs narrowing	Be more specific
NO_RESULTS_FOUND	No relevant information found	Try different keywords
RESEARCH_TIMEOUT	Research took too long	Simplify query

Error Response Format

Standard Error Response

interface ErrorResponse {
  error: string;           // Human-readable error message
  code: string;           // Machine-readable error code
  details?: any;          // Additional error details
  suggestion?: string;    // How to fix the error
  documentation?: string; // Link to relevant docs
  retryable?: boolean;   // Whether retry might succeed
}

Example Error Responses

Validation Error

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "details": {
    "issues": [
      {
        "path": "requirements",
        "message": "String too short (minimum 10 characters)"
      }
    ]
  },
  "suggestion": "Provide more detailed requirements",
  "documentation": "https://orchestre.ai/docs/api/tool-schemas#analyze_project"
}

API Error

{
  "error": "API rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 60,
    "window": "1 minute",
    "retryAfter": 45
  },
  "suggestion": "Wait 45 seconds before retrying",
  "retryable": true
}

Permission Error

{
  "error": "Cannot write to directory",
  "code": "PERMISSION_DENIED",
  "details": {
    "path": "/usr/local/projects",
    "operation": "mkdir"
  },
  "suggestion": "Choose a directory where you have write permissions"
}

Error Handling Best Practices

1. Graceful Degradation

try {
  const result = await performOperation();
  return result;
} catch (error) {
  // Try fallback approach
  try {
    const fallbackResult = await performFallback();
    return {
      ...fallbackResult,
      warning: "Used fallback method"
    };
  } catch (fallbackError) {
    // Return helpful error
    return {
      error: "Operation failed",
      code: "OPERATION_FAILED",
      suggestion: "Try again with simpler inputs"
    };
  }
}

2. Contextual Error Messages

function createContextualError(
  operation: string,
  error: Error,
  context: any
): ErrorResponse {
  return {
    error: `Failed to ${operation}`,
    code: error.name,
    details: {
      originalError: error.message,
      context: context
    },
    suggestion: getSuggestionForError(error),
    documentation: getDocumentationLink(operation)
  };
}

3. Retry Logic

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries: number = 3,
  delay: number = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      if (isRetryable(error)) {
        await new Promise(resolve => setTimeout(resolve, delay * (i + 1)));
      } else {
        throw error;
      }
    }
  }
}

Common Error Scenarios

Environment Setup

Problem: API keys not configured

Error: GEMINI_API_KEY not found
Code: API_KEY_MISSING

Solution:

export GEMINI_API_KEY="your-api-key"
# Or add to .env file

Template Initialization

Problem: Invalid project name

Error: Project name must be lowercase with hyphens
Code: INVALID_PROJECT_NAME

Solution:

# Bad: "My Project", "my_project", "MyProject"
# Good: "my-project", "awesome-app", "saas-platform"

File Operations

Problem: Cannot read file

Error: ENOENT: no such file or directory
Code: FILE_NOT_FOUND

Solution:

• Verify file path is correct
• Check if file exists
• Ensure proper permissions

API Limits

Problem: Rate limit exceeded

Error: Too many requests
Code: RATE_LIMIT_EXCEEDED

Solution:

• Implement exponential backoff
• Reduce parallel operations
• Cache results when possible

Error Recovery Strategies

1. Automatic Recovery

// Automatic retry with exponential backoff
async function autoRecover<T>(
  operation: () => Promise<T>
): Promise<T> {
  const delays = [1000, 2000, 4000, 8000];
  
  for (const delay of delays) {
    try {
      return await operation();
    } catch (error) {
      if (!isRecoverable(error)) throw error;
      await sleep(delay);
    }
  }
  
  throw new Error("Max retries exceeded");
}

2. User Intervention

// Request user input for recovery
function requestUserIntervention(error: ErrorResponse): string {
  return `
Error: ${error.error}

${error.suggestion || "Please check your inputs and try again"}

Need help? See: ${error.documentation || "/troubleshooting"}
`;
}

3. Fallback Options

// Provide alternative approaches
function suggestAlternatives(error: ErrorResponse): string[] {
  switch (error.code) {
    case "TEMPLATE_NOT_FOUND":
      return [
        "Use a different template",
        "Create a custom template",
        "Start with a minimal setup"
      ];
    case "API_KEY_MISSING":
      return [
        "Set up environment variables",
        "Use local development mode",
        "Check documentation for setup"
      ];
    default:
      return ["Retry the operation", "Check the logs", "Contact support"];
  }
}

Debugging Errors

Enable Debug Mode

# Set debug environment variable
export ORCHESTRE_DEBUG=true

# Or in code
process.env.ORCHESTRE_DEBUG = "true";

Debug Output Format

if (process.env.ORCHESTRE_DEBUG) {
  console.error("[DEBUG]", {
    timestamp: new Date().toISOString(),
    operation: "analyzeProject",
    input: params,
    error: error.stack,
    context: {
      cwd: process.cwd(),
      env: process.env.NODE_ENV
    }
  });
}

Error Logging

function logError(error: Error, context: any): void {
  const errorLog = {
    timestamp: new Date().toISOString(),
    error: {
      message: error.message,
      stack: error.stack,
      code: error.code
    },
    context,
    system: {
      platform: process.platform,
      node: process.version,
      memory: process.memoryUsage()
    }
  };
  
  // Write to error log
  fs.appendFileSync(
    ".orchestre/errors.log",
    JSON.stringify(errorLog) + "\n"
  );
}

See Also

• Troubleshooting Guide
• API Reference
• Environment Setup
• FAQ