Troubleshooting Guide

Common issues and solutions when working with the ChatGPT SDK and MCP integration.

API Errors

401 Unauthorized

Problem: Invalid or missing OpenAI API key

Solutions:

# Verify environment variable is set
echo $OPENAI_API_KEY

# Check Vercel dashboard for env vars
vercel env ls

# Redeploy after adding env vars
vercel --prod

429 Rate Limit Exceeded

Problem: Too many requests to OpenAI API

Solutions:

// Implement exponential backoff
import { retry } from 'ai';

const result = streamText({
  model: openai('gpt-4o'),
  messages,
  experimental_retry: retry({
    maxRetries: 3,
    delay: 1000,
  }),
});

Or use a rate limiter:

import { Ratelimit } from '@upstash/ratelimit';

const ratelimit = new Ratelimit({
  redis: Redis.fromEnv(),
  limiter: Ratelimit.slidingWindow(5, '1 m'),
});

Streaming Issues

Stream Not Working

Problem: Response not streaming, only returns at end

Solutions:

Check runtime configuration:

export const runtime = 'edge'; // or 'nodejs'
export const dynamic = 'force-dynamic';

Verify response headers:

return result.toDataStreamResponse({
  headers: {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
  },
});

Check client-side implementation:

const { messages, input, handleInputChange, handleSubmit } = useChat({
  api: '/api/chat',
  streamProtocol: 'text', // or 'data'
});

Stream Interrupted

Problem: Stream stops mid-response

Solutions:

Increase maxDuration in Vercel config
Check for client-side timeouts
Verify network stability

{
  "functions": {
    "app/api/chat/route.ts": {
      "maxDuration": 300
    }
  }
}

Tool Calling Issues

Tools Not Being Called

Problem: Model responds with text instead of calling tools

Solutions:

Improve tool descriptions:

const tools = {
  searchEmails: {
    description: 'REQUIRED: Use this tool to search for emails. Always use this when the user asks about emails.',
    parameters: z.object({
      query: z.string().describe('The search query string'),
    }),
    execute: async ({ query }) => { /* ... */ },
  },
};

Use maxSteps for multi-step tool calls:

const result = streamText({
  model: openai('gpt-4o'),
  messages,
  maxSteps: 5, // Allow up to 5 tool interactions
  tools,
});

Tool Execution Errors

Problem: Tool throws error during execution

Solutions:

const tools = {
  riskyOperation: {
    description: 'Perform a risky operation',
    parameters: z.object({ id: z.string() }),
    execute: async ({ id }) => {
      try {
        const result = await performOperation(id);
        return { success: true, data: result };
      } catch (error) {
        return { 
          success: false, 
          error: error instanceof Error ? error.message : 'Unknown error' 
        };
      }
    },
  },
};

TypeScript Errors

Type Mismatch

Problem: Type errors with tool parameters

Solution:

import { z } from 'zod';

const toolSchema = z.object({
  query: z.string(),
  limit: z.number().optional(),
});

const tools = {
  search: {
    description: 'Search items',
    parameters: toolSchema,
    execute: async (params: z.infer<typeof toolSchema>) => {
      // Type-safe params
      const { query, limit = 10 } = params;
      // ...
    },
  },
};

Build Errors

Module Not Found

Problem: Cannot find module '@ai-sdk/openai'

Solution:

# Clear node_modules and reinstall
rm -rf node_modules bun.lockb
bun install

# Verify package is in package.json
grep "@ai-sdk/openai" package.json

Edge Runtime Compatibility

Problem: Module incompatible with Edge Runtime

Solution:

// Use Node.js runtime instead
export const runtime = 'nodejs';

// Or use dynamic imports for incompatible modules
const { heavyModule } = await import('./heavy-module');

Debugging Tips

Enable Debug Logging

export async function POST(req: Request) {
  console.log('Chat request received:', {
    timestamp: new Date().toISOString(),
    messageCount: messages.length,
  });

  try {
    const result = streamText({
      model: openai('gpt-4o'),
      messages,
      tools,
      onFinish: (finish) => {
        console.log('Chat completed:', {
          finishReason: finish.finishReason,
          tokenUsage: finish.usage,
        });
      },
    });

    return result.toDataStreamResponse();
  } catch (error) {
    console.error('Chat error:', error);
    throw error;
  }
}

Test Tools in Isolation

// app/api/test-tool/route.ts
export async function POST(req: Request) {
  const { toolName, params } = await req.json();
  
  const tools = {
    searchEmails: async (p: any) => { /* ... */ },
    sendEmail: async (p: any) => { /* ... */ },
  };
  
  const result = await tools[toolName as keyof typeof tools](params);
  return Response.json(result);
}

Getting Help

If issues persist:

Check Vercel AI SDK documentation
Review OpenAI API status
Enable verbose logging and check Vercel function logs
Test with a minimal reproduction case

Troubleshooting

On this page