RelayPlane SDK Troubleshooting Guide

Comprehensive guide to resolve common issues with RelayPlane SDK integration

Last Updated: July 18, 2025

🚨 Most Common Issues

1. "Model not available" Errors

Error Message:

Model "claude-opus-4-20250514" is not available or accessible (FIXED in v0.4.3)

Root Cause: Using model names that don't exist or are no longer supported.

Solution:

// ✅ Use these confirmed working models
const workingModels = [
  'claude-3-7-sonnet-20250219',
  'claude-3-5-sonnet-20241022',
  'claude-3-5-haiku-20241022'
];

const result = await RelayPlane.ask("Your question", {
  model: 'claude-3-7-sonnet-20250219'  // Use working model
});

2. Timeout Issues

Error Message:

Request timeout after 30000ms

Root Cause: Default timeouts are too aggressive for slow machines or complex queries.

Solution:

// Global timeout configuration
RelayPlane.configure({
  timeout: 120000,  // 2 minutes for slow machines
  debug: true       // Enable detailed logging
});

// Per-request timeout
const result = await RelayPlane.ask("Complex analysis", {
  timeout: 180000   // 3 minutes for complex tasks
});

3. Response Format Issues

Error Message:

responseText.substring is not a function

Root Cause: Server returning streaming responses that SDK can't parse.

Solution:

// Enable debug mode to see raw responses
RelayPlane.configure({
  debug: true
});

// Handle different response formats
try {
  const result = await RelayPlane.ask("Your question");
  
  if (result && result.response) {
    console.log('✅ Response received:', result.response);
  } else {
    console.error('❌ Unexpected response format:', result);
  }
} catch (error) {
  console.error('❌ Request failed:', error.message);
}

🐌 Slow Machine Optimizations

Performance Symptoms:

• Requests taking 30+ seconds
• Frequent timeouts
• High CPU usage during requests
• Memory usage spikes

1. Increase Timeouts

// Conservative timeouts
RelayPlane.configure({
  timeout: 300000,  // 5 minutes
  debug: true,
  defaultOptimization: {
    enabled: false  // Disable overhead
  }
});

2. Use Faster Models

// Fast model for simple tasks
const result = await RelayPlane.ask(
  "Simple question", {
    model: 'claude-3-5-haiku-20241022',
    maxTokens: 200
  }
);

🌐 Network and Connectivity Issues

Common Symptoms:

• Intermittent connection failures
• Slow response times
• DNS resolution errors

Test Network Connection:

// Verify connectivity
const testConnection = async () => {
  try {
    const result = await RelayPlane.ask("Hello", {
      timeout: 30000,
      maxTokens: 50
    });
    console.log('✅ Connection working:', result.response);
  } catch (error) {
    console.error('❌ Connection failed:', error.message);
  }
};

🔧 Development Environment Issues

Environment Variables Check:

// Check required environment variables
const requiredEnvVars = ['RELAY_API_KEY', 'RELAY_BASE_URL'];

requiredEnvVars.forEach(varName => {
  if (!process.env[varName]) {
    console.error(`❌ Missing: ${varName}`);
  } else {
    console.log(`✅ ${varName} is set`);
  }
});

Development Configuration:

// Development-specific settings
if (process.env.NODE_ENV === 'development') {
  RelayPlane.configure({
    timeout: 180000,     // Longer timeout for dev
    debug: true,         // Enable detailed logging
    baseUrl: process.env.RELAY_BASE_URL || 'http://localhost:3001'
  });
}

🔍 Debugging Steps

1. Enable Debug Mode

RelayPlane.configure({
  debug: true
});

Shows request details, response timing, and error details

2. Basic Test

const result = await RelayPlane.ask(
  "Say hello", {
    timeout: 30000,
    maxTokens: 50
  }
);

Test basic connectivity with a simple query

📋 Error Code Reference

Error Type	Common Causes	Solutions
`RelayTimeoutError`	Slow machine, complex query	Increase timeout, use faster model
`RelayModelError`	Invalid model name	Use confirmed working models
`RelayNetworkError`	Connection issues	Check network, verify base URL
`RelayAuthError`	Invalid API key	Verify RELAY_API_KEY
`RelayRateLimitError`	Too many requests	Implement backoff, reduce frequency

🎯 Performance Benchmarks

Expected response times by environment:

Environment	Simple Query	Complex Query	Timeout Recommendation
Fast Machine	5-10s	15-30s	60s
Slow Machine	10-20s	30-60s	120s
Development	10-25s	30-90s	180s
Limited Bandwidth	15-30s	45-120s	300s

🆘 Getting Help

Quick Diagnostic Commands

# Test your setup
npx @relayplane/cli test

# See error recovery demos
npx @relayplane/cli demo

Community Support

Before Reporting Issues

1. Enable debug mode
2. Test with a simple query
3. Check environment variables
4. Verify model names
5. Include error logs and configuration