Troubleshooting & FAQ

Message Persistence

Message Persistence After Reload

Problem: Chat messages don’t persist after page reload

Symptoms:

• Messages appear in sidebar history
• Database contains messages
• Main chat window is empty after refresh

Solution: Synchronize MessagesProvider with useChat hook

// app/components/chat/use-chat-core.ts
export function useChatCore({ initialMessages, ... }) {
  const hasSyncedInitialMessagesRef = useRef(false)
 
  // Critical: Sync messages from database
  useEffect(() => {
    if (initialMessages.length > 0 &&
        !hasSyncedInitialMessagesRef.current &&
        status === "ready") {
 
      // Convert Message[] to UIMessage[]
      const uiMessages = initialMessages.map(msg => ({
        id: msg.id,
        role: msg.role,
        parts: [{ type: 'text', text: msg.content }]
      }))
 
      setMessages(uiMessages)
      hasSyncedInitialMessagesRef.current = true
    }
  }, [initialMessages, messages.length, setMessages, status])
}

Additional Checks:

// Verify messages are loaded from database
console.log('Messages from DB:', initialMessages.length)
console.log('Messages in UI:', messages.length)

Type Errors

TypeScript Type Errors

Problem: Type incompatibilities with AI SDK v5

Common Errors:

• Property 'content' does not exist on type 'UIMessage'
• Type 'LanguageModelV1' is not assignable to type 'LanguageModel'
• Property 'isLoading' does not exist on type 'UseChatHelpers'

Solutions:

1. Message Type Conversion

// Convert between Message and UIMessage
function convertToUIMessage(message: Message): UIMessage {
  return {
    id: message.id,
    role: message.role as 'user' | 'assistant' | 'system',
    parts: [{ type: 'text', text: message.content }]
  }
}
 
// Extract text from UIMessage
function getTextContent(message: UIMessage): string {
  return message.parts
    .filter((part): part is { type: 'text'; text: string } =>
      part.type === 'text'
    )
    .map(part => part.text)
    .join('')
}

2. Provider Types

// Use LanguageModel instead of LanguageModelV1
import type { LanguageModel } from 'ai'
// NOT: import type { LanguageModelV1 } from 'ai'

3. Type Assertions for Compatibility

// When strict types are incompatible
const chatHelpers = useChat({
  initialMessages: [],
  onFinish: cacheAndAddMessage as any,
} as any)
 
const isLoading = (chatHelpers as any).isLoading

Streaming Issues

Streaming Response Issues

Problem: sendMessage format error

TypeError: Cannot use 'in' operator to search for 'text' in hello

Solution: Use object format instead of string

// Wrong - AI SDK v3/v4 format
await sendMessage('Hello')
 
// Correct - AI SDK v5 format
await sendMessage({ text: 'Hello' }, options)

Problem: Streaming status not updating

Solution: Access status from extended properties

const chatHelpers = useChat({...})
const status = (chatHelpers as any).status || 'ready'
 
// Use status for UI updates
{status === 'streaming' && <Loader />}
{status === 'ready' && <Message />}

API Errors

GPT-4o API Errors

Problem: Authentication failed

{
  "error": {
    "message": "Incorrect API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Solutions:

1. Verify API Key

   // Check environment variable
   console.log('API Key exists:', !!process.env.OPENAI_API_KEY);
   console.log('Key prefix:', process.env.OPENAI_API_KEY?.substring(0, 7));
    
   // Ensure key is properly formatted
   const apiKey = process.env.OPENAI_API_KEY?.trim();

2. Update Environment Variables

   # Local development
   echo "OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx" >> .env.local
    
   # Vercel production
   vercel env add OPENAI_API_KEY production

3. Check API Key Permissions

   // Test API key with minimal request
   import OpenAI from 'openai';
    
   const openai = new OpenAI({
     apiKey: process.env.OPENAI_API_KEY
   });
    
   try {
     const test = await openai.chat.completions.create({
       model: 'gpt-4o',
       messages: [{ role: 'user', content: 'Hi' }],
       max_tokens: 10
     });
     console.log('API key valid');
   } catch (error) {
     console.error('API key invalid:', error);
   }

Problem: Model not available

{
  "error": {
    "message": "The model `gpt-4o` does not exist",
    "type": "invalid_request_error"
  }
}

Solutions:

1. Check Model Access

   // List available models
   const models = await openai.models.list();
   const hasGPT4o = models.data.some(m => m.id === 'gpt-4o');
    
   if (!hasGPT4o) {
     console.log('GPT-4o not available, using fallback');
     // Fall back to gpt-4-turbo or gpt-3.5-turbo
   }

2. Use Vercel AI SDK with Fallback

   import { openai } from '@ai-sdk/openai';
   import { anthropic } from '@ai-sdk/anthropic';
    
   async function getAIResponse(messages: any[]) {
     try {
       // Try GPT-4o first
       return await streamText({
         model: openai('gpt-4o'),
         messages
       });
     } catch (error) {
       // Fallback to Claude
       return await streamText({
         model: anthropic('claude-3-opus-20240229'),
         messages
       });
     }
   }

Rate Limiting

Rate Limiting Issues

Problem: Too many requests error

{
  "error": {
    "message": "Rate limit reached",
    "type": "rate_limit_error"
  }
}

Solutions:

1. Implement Exponential Backoff

   async function withRetry<T>(
     fn: () => Promise<T>,
     maxRetries = 3
   ): Promise<T> {
     let lastError;
    
     for (let i = 0; i < maxRetries; i++) {
       try {
         return await fn();
       } catch (error: any) {
         lastError = error;
    
         if (error.status === 429) {
           // Rate limited - wait exponentially
           const delay = Math.min(1000 * Math.pow(2, i), 30000);
           await new Promise(resolve => setTimeout(resolve, delay));
         } else {
           throw error;
         }
       }
     }
     throw lastError;
   }

2. Use Request Queue

   import pLimit from 'p-limit';
    
   const gpt4oLimit = pLimit(5); // Max 5 concurrent requests
    
   export async function queueGPT4oRequest(request: () => Promise<any>) {
     return gpt4oLimit(request);
   }

Problem: Token limit exceeded

{
  "error": {
    "message": "This model's maximum context length is 128000 tokens",
    "type": "invalid_request_error"
  }
}

Solutions:

1. Implement Token Counting

   import { encoding_for_model } from 'tiktoken';
    
   function countTokens(text: string): number {
     const encoding = encoding_for_model('gpt-4');
     const tokens = encoding.encode(text);
     encoding.free();
     return tokens.length;
   }
    
   // Trim messages if needed
   function trimToTokenLimit(messages: any[], limit = 120000) {
     let totalTokens = 0;
     const trimmed = [];
    
     for (const msg of messages.reverse()) {
       const tokens = countTokens(JSON.stringify(msg));
       if (totalTokens + tokens > limit) break;
       totalTokens += tokens;
       trimmed.unshift(msg);
     }
    
     return trimmed;
   }

2. Use Conversation Summarization

   async function summarizeOldMessages(messages: any[]) {
     if (messages.length > 20) {
       const oldMessages = messages.slice(0, -10);
       const summary = await openai.chat.completions.create({
         model: 'gpt-3.5-turbo', // Use cheaper model for summarization
         messages: [
           {
             role: 'user',
             content: `Summarize: ${JSON.stringify(oldMessages)}`
           }
         ],
         max_tokens: 500
       });
    
       return [
         { role: 'assistant', content: summary.choices[0].message.content },
         ...messages.slice(-10)
       ];
     }
     return messages;
   }

Streaming Issues

Streaming Response Issues

Problem: SSE connection drops

Error: EventSource connection lost

Solutions:

1. Implement Reconnection Logic

   class RobustEventSource {
     private eventSource: EventSource | null = null;
     private url: string;
     private reconnectAttempts = 0;
    
     constructor(url: string) {
       this.url = url;
       this.connect();
     }
    
     connect() {
       this.eventSource = new EventSource(this.url);
    
       this.eventSource.onopen = () => {
         this.reconnectAttempts = 0;
         console.log('SSE connected');
       };
    
       this.eventSource.onerror = () => {
         this.eventSource?.close();
    
         // Exponential backoff reconnection
         const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
         setTimeout(() => this.connect(), delay);
         this.reconnectAttempts++;
       };
     }
   }

2. Handle Stream Interruptions

   import { streamText } from 'ai';
    
   const response = await streamText({
     model: openai('gpt-4o'),
     messages,
     onFinish: ({ text, usage }) => {
       // Save completed response
       console.log('Stream completed:', { text, usage });
     }
   });
    
   try {
     for await (const chunk of response.textStream) {
       // Process chunk
       process.stdout.write(chunk);
     }
   } catch (error) {
     console.error('Stream interrupted:', error);
     // Resume from last position if needed
   }

Problem: WebSocket disconnections (Realtime API)

Error: WebSocket connection closed unexpectedly

Solutions:

1. Implement Heartbeat

   class RealtimeManager {
     private ws: WebSocket | null = null;
     private heartbeatInterval: NodeJS.Timeout | null = null;
    
     connect(url: string) {
       this.ws = new WebSocket(url);
    
       this.ws.onopen = () => {
         // Start heartbeat
         this.heartbeatInterval = setInterval(() => {
           if (this.ws?.readyState === WebSocket.OPEN) {
             this.ws.send(JSON.stringify({ type: 'ping' }));
           }
         }, 30000); // Every 30 seconds
       };
    
       this.ws.onclose = () => {
         if (this.heartbeatInterval) {
           clearInterval(this.heartbeatInterval);
         }
         // Reconnect after delay
         setTimeout(() => this.connect(url), 5000);
       };
     }
   }

Vision Problems

Vision API Problems

Problem: Image analysis failed

{
  "error": {
    "message": "Invalid image format or size",
    "type": "invalid_request_error"
  }
}

Solutions:

1. Validate and Resize Images

   import sharp from 'sharp';
    
   async function prepareImageForGPT4o(
     imageBuffer: Buffer,
     maxSize = 20 * 1024 * 1024 // 20MB
   ): Promise<string> {
     // Check size
     if (imageBuffer.length > maxSize) {
       // Resize if too large
       imageBuffer = await sharp(imageBuffer)
         .resize(2048, 2048, {
           fit: 'inside',
           withoutEnlargement: true
         })
         .jpeg({ quality: 85 })
         .toBuffer();
     }
    
     // Convert to base64
     return `data:image/jpeg;base64,${imageBuffer.toString('base64')}`;
   }

2. Handle Vision Requests

   async function analyzeImage(imageUrl: string, prompt: string) {
     try {
       const response = await openai.chat.completions.create({
         model: 'gpt-4o',
         messages: [
           {
             role: 'user',
             content: [
               { type: 'text', text: prompt },
               { type: 'image_url', image_url: { url: imageUrl } }
             ]
           }
         ],
         max_tokens: 1000
       });
    
       return response.choices[0].message.content;
     } catch (error) {
       console.error('Vision API error:', error);
       // Fallback to alternative vision model
       return await analyzeWithGeminiVision(imageUrl, prompt);
     }
   }