Troubleshooting - Adaptive

Common Issues

Authentication Problems

401 Unauthorized Error

Problem: Getting authentication errors when making API calls.Solutions:

Check your API key:

# Verify your API key is set correctly
echo $ADAPTIVE_API_KEY

Ensure correct format:

// Correct - no 'Bearer' prefix needed
const openai = new OpenAI({
  apiKey: 'your-adaptive-api-key',
  baseURL: 'https://llmadaptive.uk/api/v1'
});

Verify API key validity:
- Check if your API key has expired
- Ensure you’re using the correct key for your environment
- Try regenerating your API key in the dashboard

Test with curl:

curl -H "X-Stainless-API-Key: your-adaptive-api-key" \
     -H "Content-Type: application/json" \
     https://llmadaptive.uk/api/v1/chat/completions \
     -d '{"model":"","messages":[{"role":"user","content":"test"}]}'

API Key Not Found

Problem: Environment variable not being loaded.Solutions:

Check environment variable:

# In terminal
export ADAPTIVE_API_KEY=your-key-here

# Or in .env file
echo "ADAPTIVE_API_KEY=your-key-here" >> .env

Load environment variables:

// Node.js
require('dotenv').config();

// Or using ES modules
import 'dotenv/config';

Python environment:

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv("ADAPTIVE_API_KEY")

Configuration Issues

Wrong Base URL

Problem: Using incorrect base URL causing connection failures.Correct base URL:

https://llmadaptive.uk/api/v1

Common mistakes:

// ❌ Wrong
baseURL: 'https://api.openai.com/v1'
baseURL: 'https://adaptive.ai/api/v1'
baseURL: 'https://llmadaptive.uk/v1'

// ✅ Correct
baseURL: 'https://llmadaptive.uk/api/v1'

Model Parameter Issues

Problem: Intelligent routing not working or model errors.Solutions:

Use empty string for intelligent routing:

// ✅ Correct - enables intelligent routing
model: ""

// ❌ Wrong - tries to use specific model
model: "gpt-3.5-turbo"
model: null
model: undefined

TypeScript type issues:

// Option 1: Type assertion
model: "" as any

// Option 2: Disable strict checking for this parameter
// @ts-ignore
model: ""

SSL/TLS Certificate Errors

Problem: Certificate validation errors in some environments.Solutions:

Update certificates:

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

Node.js certificate issues:

// Temporary workaround (not recommended for production)
process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = 0;

// Better solution: update Node.js or certificates

Python certificate issues:

import ssl
import certifi

# Ensure certificates are up to date
ssl.create_default_context(cafile=certifi.where())

Request/Response Issues

Empty or No Response

Problem: Getting empty responses or no content.Diagnostic steps:

Check request format:

const completion = await openai.chat.completions.create({
  model: "",
  messages: [
    { role: "user", content: "Hello" } // Ensure content is not empty
  ]
});

Verify response handling:

console.log("Full response:", completion);
console.log("Content:", completion.choices[0]?.message?.content);
console.log("Provider:", completion.provider);

Check for API errors:

try {
  const completion = await openai.chat.completions.create({...});
} catch (error) {
  console.log("Error details:", error);
  console.log("Status:", error.status);
  console.log("Message:", error.message);
}

Streaming Not Working

Problem: Streaming responses not appearing or failing.Solutions:

Check streaming syntax:

// ✅ Correct streaming setup
const stream = await openai.chat.completions.create({
  model: "",
  messages: [...],
  stream: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

Browser streaming with fetch:

const response = await fetch('/api/stream-chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  // Process chunk...
}

Server-sent events setup:

// Server
res.writeHead(200, {
  'Content-Type': 'text/event-stream',
  'Cache-Control': 'no-cache',
  'Connection': 'keep-alive'
});

Rate Limiting Errors

Problem: Getting 429 errors (rate limit exceeded).Solutions:

Implement exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
}

Check your rate limits:
- Free tier: 100 requests/minute
- Pro tier: 1,000 requests/minute
- Enterprise: Custom limits

Implement request queuing:

class RequestQueue {
  constructor(maxPerMinute = 100) {
    this.queue = [];
    this.maxPerMinute = maxPerMinute;
    this.requestTimes = [];
  }
  
  async enqueue(requestFn) {
    return new Promise((resolve, reject) => {
      this.queue.push({ requestFn, resolve, reject });
      this.processQueue();
    });
  }
  
  async processQueue() {
    if (this.queue.length === 0) return;
    
    const now = Date.now();
    this.requestTimes = this.requestTimes.filter(time => now - time < 60000);
    
    if (this.requestTimes.length < this.maxPerMinute) {
      const { requestFn, resolve, reject } = this.queue.shift();
      this.requestTimes.push(now);
      
      try {
        const result = await requestFn();
        resolve(result);
      } catch (error) {
        reject(error);
      }
      
      // Process next request
      setTimeout(() => this.processQueue(), 100);
    } else {
      // Wait and try again
      setTimeout(() => this.processQueue(), 1000);
    }
  }
}

Integration-Specific Issues

LangChain Integration Problems

Problem: LangChain not working with Adaptive.Solutions:

Correct LangChain setup:

# Python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    api_key=os.getenv("ADAPTIVE_API_KEY"),
    base_url="https://llmadaptive.uk/api/v1",
    model=""  # Important: empty string
)

// JavaScript
import { ChatOpenAI } from "@langchain/openai";

const llm = new ChatOpenAI({
  apiKey: process.env.ADAPTIVE_API_KEY,
  configuration: {
    baseURL: "https://llmadaptive.uk/api/v1"
  },
  model: ""
});

Handle LangChain-specific errors:

from openai import APIError

try:
    response = llm.invoke("Hello")
except APIError as e:
    print(f"API Error: {e}")
except Exception as e:
    print(f"Other error: {e}")

Vercel AI SDK Issues

Problem: Vercel AI SDK not connecting properly.Solutions:

Using OpenAI provider method:

import { openai } from '@ai-sdk/openai';

const adaptiveOpenAI = openai({
  apiKey: process.env.ADAPTIVE_API_KEY,
  baseURL: 'https://llmadaptive.uk/api/v1',
});

const { text } = await generateText({
  model: adaptiveOpenAI(''), // Empty string for routing
  prompt: 'Hello'
});

TypeScript issues:

// If getting type errors
const model = adaptiveOpenAI('' as any);

Environment variables in Next.js:

// next.config.js
module.exports = {
  env: {
    ADAPTIVE_API_KEY: process.env.ADAPTIVE_API_KEY,
  },
};

Performance Issues

Slow Response Times

Problem: Responses taking longer than expected.Diagnostic steps:

Check routing decisions:

const completion = await openai.chat.completions.create({
  model: "",
  messages: [...]
});

console.log("Selected provider:", completion.provider);
console.log("Selected model:", completion.model);

Optimize with cost_bias:

// Prefer faster, cheaper models
const completion = await openai.chat.completions.create({
  model: "",
  messages: [...],
  cost_bias: 0.2 // 0 = cheapest/fastest, 1 = best quality
});

Use provider constraints for speed:

// Route only to fast providers
const completion = await openai.chat.completions.create({
  model: "",
  messages: [...],
  provider_constraint: ["groq", "gemini"] // Fast providers
});

High Latency

Problem: Network latency issues.Solutions:

Check your network:

# Test connectivity
ping llmadaptive.uk

# Test TLS handshake
curl -w "@curl-format.txt" -o /dev/null https://llmadaptive.uk/api/v1/

Implement timeout handling:

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 30000); // 30s timeout

try {
  const completion = await openai.chat.completions.create({
    model: "",
    messages: [...]
  }, {
    signal: controller.signal
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request timed out');
  }
} finally {
  clearTimeout(timeoutId);
}

Use connection pooling:

import https from 'https';

const agent = new https.Agent({
  keepAlive: true,
  maxSockets: 10
});

const openai = new OpenAI({
  apiKey: process.env.ADAPTIVE_API_KEY,
  baseURL: 'https://llmadaptive.uk/api/v1',
  httpAgent: agent
});

Development Environment Issues

CORS Issues in Browser

Problem: Cross-origin resource sharing errors.Solutions:

Never call API directly from browser:

// ❌ Wrong - exposes API key
// const completion = await openai.chat.completions.create({...});

// ✅ Correct - use your backend
const response = await fetch('/api/chat', {
  method: 'POST',
  body: JSON.stringify({ message })
});

Set up proxy in development:

// Next.js API route
// pages/api/chat.js
export default async function handler(req, res) {
  const completion = await openai.chat.completions.create({
    model: "",
    messages: req.body.messages
  });
  
  res.json({ response: completion.choices[0].message.content });
}

Configure CORS for your backend:

// Express.js
app.use(cors({
  origin: ['http://localhost:3000', 'https://yourdomain.com'],
  credentials: true
}));

TypeScript Compilation Errors

Problem: TypeScript errors with Adaptive integration.Solutions:

Install correct types:

npm install --save-dev @types/node
npm install openai  # Latest version includes types

Type assertion for model parameter:

const completion = await openai.chat.completions.create({
  model: "" as any, // Type assertion
  messages: [...]
});

Create custom types if needed:

interface AdaptiveCompletion extends ChatCompletion {
  provider: string;
}

Module Import Errors

Problem: ES modules vs CommonJS issues.Solutions:

Use correct imports:

// ES modules
import OpenAI from 'openai';

// CommonJS
const OpenAI = require('openai');

Package.json configuration:

{
  "type": "module",
  "dependencies": {
    "openai": "^4.0.0"
  }
}

Node.js version compatibility:

# Check Node.js version
node --version

# Adaptive requires Node.js 18+
# Update if necessary

Getting Help

Debug Information to Collect

When reporting issues, please include:

Environment details:

# System info
node --version
npm --version

# Package versions
npm list openai
npm list @langchain/openai

Request details:

// Sanitized request (remove API key)
{
  "model": "",
  "messages": [...],
  "provider_constraint": [...],
  "cost_bias": 0.5
}

Error information:

console.log("Error status:", error.status);
console.log("Error message:", error.message);
console.log("Error stack:", error.stack);

Network diagnostics:

# Test connectivity
curl -I https://llmadaptive.uk/api/v1/

# DNS resolution
nslookup llmadaptive.uk

Support Channels

Documentation

Check our comprehensive guides and API reference for solutions

GitHub Issues

Report bugs and request features on our GitHub repository

Discord Community

Get help from the community and Adaptive team members

Email Support

Contact support@adaptive.com for priority assistance

Best Practices for Debugging

Start with simple requests:

// Test basic functionality first
const simple = await openai.chat.completions.create({
  model: "",
  messages: [{ role: "user", content: "Hello" }]
});

Enable verbose logging:

// Add detailed logging
console.log("Request:", JSON.stringify(requestData, null, 2));
console.log("Response:", JSON.stringify(response, null, 2));

Test with curl:

# Verify API access outside your application
curl -X POST https://llmadaptive.uk/api/v1/chat/completions \
  -H "X-Stainless-API-Key: $ADAPTIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"","messages":[{"role":"user","content":"test"}]}'

Isolate the problem:
- Test different messages
- Try different parameters
- Test in different environments
- Compare with working examples

FAQ

Why am I not getting responses from certain providers?

How do I know which provider was selected?

Can I force a specific model?

Why are my costs higher than expected?

​Common Issues

​Authentication Problems

​Configuration Issues

​Request/Response Issues

​Integration-Specific Issues

​Performance Issues

​Development Environment Issues

​Getting Help

​Debug Information to Collect

​Support Channels