What the Vercel AI SDK is — and its error philosophy

The Vercel AI SDK — the ai package on npm — is the TypeScript/JavaScript library most Next.js and Node teams reach for when they want to add AI features without wiring up every provider by hand. It presents a single API surface for Claude, GPT, Gemini, and dozens of other providers; it handles streaming for you; it plugs into React with hooks like useChat. What it does not do — and this is where most teams get in trouble — is hide the fact that AI providers fail in a hundred different ways.

Every error you'll see falls into one of three categories:

Why the SDK's error philosophy trips people up

The SDK's design goal is provider portability: swap Claude for GPT with a one-line change. To do that, it normalizes provider errors into its own hierarchy. But normalization is lossy. The Anthropic-specific overloaded_error (529) becomes an AI_APICallError with a status of 529 and a hint at the underlying provider — but if your retry logic was watching for the specific class name, it won't match.

The right mental model: SDK errors give you the shape of the problem (rate limit, invalid request, timeout). The cause field and data preserve the underlying provider's original response for when you need provider-specific handling.

Version context: this guide covers v5

The SDK went through significant revisions across versions. As of September 2026, v5 is the current major version. This guide's code samples target v5, with notes on where v3/v4 patterns still appear in the wild. Chapter 10 covers migration issues specifically.

// package.json snippet
{
  "dependencies": {
    "ai": "^5.0.0",
    "@ai-sdk/anthropic": "^2.0.0",
    "@ai-sdk/openai": "^2.0.0",
    "@ai-sdk/google": "^2.0.0"
  }
}

What this guide covers

Chapter 2 lays out the full error class hierarchy so you know what you're catching. Chapters 3-7 cover the specific categories of error you'll actually see in production. Chapters 8-11 cover the operational side — retry, telemetry, debugging. Chapter 12 packages everything into a production wrapper you can drop in.

Every code sample has been tested against the actual SDK. Where a fix depends on a specific version, we say so. Where the correct answer is "don't use the SDK for this" (yes, that's occasionally the correct answer), we say so.

The error class hierarchy — what you're actually catching

The SDK exports a family of error classes, all extending a common AISDKError base. Learning the hierarchy is the difference between "something went wrong" and actionable error handling.

The core classes you'll actually see

import {
  AISDKError,            // base class
  APICallError,          // provider returned an error
  InvalidPromptError,    // your prompt is malformed
  InvalidArgumentError,  // wrong argument to an SDK function
  InvalidResponseDataError,  // provider returned unparseable data
  JSONParseError,        // failed to parse a JSON response
  LoadAPIKeyError,       // no API key found
  NoContentGeneratedError,   // provider returned empty
  NoObjectGeneratedError,    // generateObject failed to produce valid output
  NoSuchModelError,      // requested model doesn't exist
  NoSuchProviderError,   // requested provider isn't registered
  NoSuchToolError,       // tool referenced but not defined
  ToolCallRepairError,   // tool call couldn't be repaired
  TypeValidationError,   // Zod schema validation failed
  UnsupportedFunctionalityError,  // feature not supported by provider
} from 'ai';

The inheritance chain

AISDKError
├── APICallError                    // wraps provider HTTP errors
│   ├── (has: url, requestBodyValues, statusCode, responseHeaders,
│   │        responseBody, cause, isRetryable)
├── InvalidPromptError              // messages array or prompt malformed
├── InvalidArgumentError            // wrong argument shape
├── InvalidResponseDataError        // provider returned garbage
├── JSONParseError                  // JSON.parse failed on response
├── LoadAPIKeyError                 // env vars missing
├── NoContentGeneratedError         // empty response
├── NoObjectGeneratedError          // generateObject-specific
│   ├── (has: cause, response, usage, finishReason)
├── NoSuchModelError                // "gpt-99" — model doesn't exist
├── NoSuchProviderError             // no provider registered for this ID
├── NoSuchToolError                 // model called a tool that isn't defined
├── ToolCallRepairError             // repair mechanism failed
├── TypeValidationError             // Zod validation failed on output
└── UnsupportedFunctionalityError   // provider can't do this

Detecting SDK errors safely

Every SDK error has a static .isInstance() method that works across bundling and duplicated instances. Prefer it over instanceof for library-boundary code.

import { APICallError, TypeValidationError, NoObjectGeneratedError } from 'ai';

try {
  const { text } = await generateText({
    model: anthropic('claude-sonnet-4-6'),
    prompt: userInput,
  });
} catch (error) {
  if (APICallError.isInstance(error)) {
    // Wrapped provider error
    console.error('API call failed', {
      status: error.statusCode,
      body: error.responseBody,
      isRetryable: error.isRetryable,
    });
  } else if (TypeValidationError.isInstance(error)) {
    // Zod schema mismatch on output
    console.error('Output failed validation', error.value);
  } else if (NoObjectGeneratedError.isInstance(error)) {
    // generateObject-specific
    console.error('Object generation failed', {
      cause: error.cause,
      partial: error.response,
    });
  } else {
    // Non-SDK error or unknown
    throw error;
  }
}

The two ways errors surface

1. Thrown from await (non-streaming)

generateText, generateObject, embed, and embedMany throw errors directly. Wrap them in try/catch.

2. Emitted in the stream (streaming)

streamText, streamObject return a result object whose stream can emit an error event, but only after successfully returning. This trips people up: the outer await streamText(...) resolves successfully even if the stream will fail later. You need to handle both.

// Non-streaming — errors thrown normally
try {
  const result = await generateText({ ... });
  return result.text;
} catch (error) { /* handle */ }

// Streaming — errors emitted mid-stream
const stream = streamText({ ... });  // may throw here for setup errors
try {
  for await (const chunk of stream.textStream) {
    // send chunk to client
  }
  const finalUsage = await stream.usage;
} catch (error) {
  // error thrown mid-stream — handle without user seeing broken chunks
}

Provider errors — how the SDK wraps them

The SDK's job is to normalize errors across providers so your code can be provider-agnostic. Understanding what gets normalized (and what gets preserved) tells you when to trust the abstraction and when to reach through it.

What normalization looks like

// Anthropic returns 529 overloaded_error
// You catch: APICallError with statusCode=529
// You get:
{
  name: 'AI_APICallError',
  message: 'API call failed with status 529: Overloaded',
  statusCode: 529,
  url: 'https://api.anthropic.com/v1/messages',
  responseHeaders: { 'retry-after': '30', ... },
  responseBody: '{"type":"error","error":{"type":"overloaded_error",...}}',
  isRetryable: true,   // SDK sets this based on status code
  data: { type: 'overloaded_error', message: 'Overloaded' },  // parsed body
  cause: undefined,  // set for wrapped exceptions
}

// OpenAI returns 429 rate_limit_exceeded
// You catch: APICallError with statusCode=429
// Structure is identical shape — different responseBody

The isRetryable flag — useful but not gospel

The SDK sets isRetryable to true for status codes 408, 409, 429, and 5xx. It's a reasonable default but not aware of your specific context. Trust it for coarse routing; make your own decisions when the underlying provider adds nuance.

function shouldRetry(error: unknown): boolean {
  if (!APICallError.isInstance(error)) return false;
  
  // Trust SDK's default for most cases
  if (!error.isRetryable) return false;
  
  // But override for specific cases
  const status = error.statusCode;
  const body = error.data as any;
  
  // 400s that shouldn't retry even if SDK says otherwise
  if (status === 400) return false;
  if (status === 422) return false;
  
  // OpenAI content_filter — retry won't help
  if (body?.error?.code === 'content_filter') return false;
  
  // Otherwise trust the SDK
  return true;
}

Extracting the underlying provider error

Sometimes you need the raw provider response — for logging, for specific handling, for showing users a provider-specific message. The responseBody and data fields preserve this.

function extractProviderError(error: APICallError) {
  const body = error.responseBody;
  const parsed = error.data;
  
  // Anthropic shape
  if (parsed && typeof parsed === 'object' && 'type' in parsed) {
    if (parsed.type === 'error' && 'error' in parsed) {
      return {
        provider: 'anthropic',
        type: (parsed as any).error?.type,
        message: (parsed as any).error?.message,
      };
    }
  }
  
  // OpenAI shape
  if (parsed && typeof parsed === 'object' && 'error' in parsed) {
    const e = (parsed as any).error;
    return {
      provider: 'openai',
      type: e?.type,
      code: e?.code,
      message: e?.message,
    };
  }
  
  // Fallback — raw body
  return { raw: body };
}

Provider-specific errors that break normalization

Anthropic 529 — overloaded_error

Comes through as APICallError with statusCode 529. Not a rate limit — the provider itself is overloaded. Retry with backoff, but recognize this as a signal to fall back to a different provider sooner than for a normal 429.

OpenAI content_filter

Returned as HTTP 200 with a finish_reason of "content_filter." Not an error in the HTTP sense — you get an NoContentGeneratedError or the response text is empty. Check finishReason on successful returns.

Gemini safety block

Returns HTTP 200 with promptFeedback.blockReason. The SDK surfaces this as either a NoContentGeneratedError or a response with finishReason: 'content-filter' depending on version. Handle both.

const result = await generateText({
  model: google('gemini-3-5-pro'),
  prompt: userInput,
});

// Check finish reason even on successful returns
if (result.finishReason === 'content-filter') {
  return { error: 'Content was blocked by safety filters' };
}
if (!result.text || result.text.length === 0) {
  return { error: 'No content generated' };
}

Streaming errors — the useChat and streamText gotchas

Streaming is where the Vercel AI SDK really earns its keep — and where errors get subtle. The client-server streaming protocol has three failure surfaces: the initial connection, mid-stream errors, and client-side parsing failures. Each fails differently and needs specific handling.

The three streaming primitives

// 1. streamText — server-side, returns a StreamTextResult
const result = streamText({
  model: anthropic('claude-sonnet-4-6'),
  messages,
});

// The result has multiple streams:
// - result.textStream — text deltas
// - result.fullStream — all events including tool calls, errors
// - result.toDataStreamResponse() — Response for API routes
// - result.toDataStream() — for custom protocols

// 2. streamObject — server-side, structured output streaming
const result = streamObject({
  model: openai('gpt-5-6'),
  schema: mySchema,
  prompt: userInput,
});

// 3. useChat — React hook, client-side consumer
const { messages, error, isLoading, reload, stop } = useChat({
  api: '/api/chat',
});

Mid-stream errors — the fullStream pattern

The textStream only yields text deltas. If an error occurs mid-stream, it's not visible on textStream. You must consume fullStream to catch mid-stream errors.

const result = streamText({
  model: anthropic('claude-sonnet-4-6'),
  messages,
});

// Wrong — silent failures
for await (const chunk of result.textStream) {
  process(chunk);
}

// Right — catches errors and finish signals
for await (const part of result.fullStream) {
  switch (part.type) {
    case 'text-delta':
      process(part.textDelta);
      break;
    case 'error':
      logger.error('Stream error', part.error);
      // Handle without breaking the client
      break;
    case 'finish':
      logger.info('Stream finished', {
        finishReason: part.finishReason,
        usage: part.usage,
      });
      break;
    case 'tool-call':
      handleToolCall(part);
      break;
    case 'tool-result':
      handleToolResult(part);
      break;
  }
}

Serverless timeouts kill streams silently

Vercel functions have execution timeouts — 60 seconds on Hobby, 300 on Pro, 900 on Enterprise. AWS Lambda has similar limits. A long generation that exceeds the timeout is cut off mid-stream and the client sees a truncated response with no explicit error.

// Set explicit timeout that matches your platform
export const maxDuration = 60; // Vercel Fluid Compute config

// Also cap max_tokens to prevent generation from exceeding budget
const result = streamText({
  model: anthropic('claude-sonnet-4-6'),
  messages,
  maxOutputTokens: 4096,  // don't let the model use the full window
});

// And add abort logic for user-cancellable requests
const result = streamText({
  model: anthropic('claude-sonnet-4-6'),
  messages,
  abortSignal: request.signal,  // fires when client disconnects
});

Client-side useChat error handling

'use client';
import { useChat } from '@ai-sdk/react';

function Chat() {
  const {
    messages,
    input,
    handleInputChange,
    handleSubmit,
    isLoading,
    error,       // set when the stream fails
    reload,      // retry the last message
    stop,        // abort the current stream
  } = useChat({
    api: '/api/chat',
    onError: (error) => {
      // Called on any stream error
      console.error('Chat error', error);
      // error is an Error instance; message contains the reason
    },
    onFinish: (message, { usage, finishReason }) => {
      // Called when stream completes normally
      analytics.track('chat_message', { usage, finishReason });
    },
  });
  
  return (
    

      {messages.map(m => /* render message */)}
      {error && (
        

          Something went wrong: {error.message}
           reload()}>Retry
        
      )}
      

        
        {isLoading && Stop}
      
    
  );
}

The data protocol mismatch bug

useChat expects the data-stream protocol by default. Your server route must return toDataStreamResponse(), not a raw text stream. If you return the wrong protocol, useChat produces confusing errors like "Failed to parse stream" or messages that never appear.

// Wrong — raw text response, useChat can't parse
export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: anthropic('claude-sonnet-4-6'),
    messages,
  });
  return new Response(result.textStream);  // useChat can't parse this
}

// Right — data stream protocol
export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = streamText({
    model: anthropic('claude-sonnet-4-6'),
    messages,
  });
  return result.toDataStreamResponse({
    // Optional: transform errors for the client
    getErrorMessage: (error) => {
      if (APICallError.isInstance(error)) {
        return `Provider error: ${error.statusCode}`;
      }
      return 'Something went wrong';
    },
  });
}

Tool calling errors — the six failure modes

Tool calling (also called function calling) is where the SDK does the most heavy lifting — and where the most subtle bugs live. Every tool call goes through schema validation, execution, result formatting, and re-injection into the conversation. Each step has its own failure modes.

Failure mode 1: NoSuchToolError

The model called a tool by a name that doesn't exist in your tools map. Usually caused by fine-tuning drift (model was trained to call a tool your app doesn't have) or prompt injection.

const result = await generateText({
  model: anthropic('claude-sonnet-4-6'),
  tools: {
    getWeather: tool({
      description: 'Get the current weather',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => fetchWeather(city),
    }),
  },
  prompt: 'What is the weather in Karachi?',
  // Fallback for tool name errors
  experimental_repairToolCall: async ({ toolCall, error, messages }) => {
    if (NoSuchToolError.isInstance(error)) {
      // Ask the model to try again with a valid tool
      return null; // returning null causes the SDK to abort the call
    }
    return null;
  },
});

Failure mode 2: InvalidToolArgumentsError / TypeValidationError

The model called a tool with arguments that fail Zod schema validation. Missing required field, wrong type, extra unexpected fields. Very common with weaker models or when the schema is complex.

tools: {
  createOrder: tool({
    description: 'Create a new order',
    inputSchema: z.object({
      customerId: z.string().uuid(),
      items: z.array(z.object({
        sku: z.string(),
        quantity: z.number().positive(),
      })).min(1),
    }),
    execute: async ({ customerId, items }) => {
      return await orderService.create(customerId, items);
    },
  }),
},
// If args fail validation, the SDK throws TypeValidationError
// Set up automatic repair:
experimental_repairToolCall: async ({ toolCall, error, tools, messages }) => {
  if (!TypeValidationError.isInstance(error)) return null;
  
  // Ask the model to fix its own arguments
  const { object: repaired } = await generateObject({
    model: anthropic('claude-sonnet-4-6'),
    schema: tools[toolCall.toolName].inputSchema,
    prompt: `The tool call had invalid arguments: ${error.message}
    Original call: ${JSON.stringify(toolCall.args)}
    Fix the arguments to match the schema.`,
  });
  return { ...toolCall, args: repaired };
},

Failure mode 3: Tool execution errors

The tool's execute function threw an exception. Database down, external API failed, permission denied. These get wrapped in the tool result.

tools: {
  fetchUserData: tool({
    description: 'Fetch data for a user',
    inputSchema: z.object({ userId: z.string() }),
    execute: async ({ userId }) => {
      try {
        return await db.users.findById(userId);
      } catch (error) {
        // Return a structured error the model can reason about
        return {
          error: true,
          message: 'Database unavailable',
          retryable: true,
        };
      }
    },
  }),
},

// The model sees the error and can respond to the user gracefully
// rather than crashing the whole request.

Failure mode 4: Missing tool result (orphan tool call)

The provider requires that every tool_use has a matching tool_result before the next assistant turn. If you drop a tool result (e.g., filtered it during context management), the next generation fails with a cryptic 400.

// Wrong — dropping a tool_result mid-conversation
const filtered = messages.filter(m => {
  if (m.role === 'tool' && looksLikeError(m.content)) {
    return false;  // BUG: model expected this tool_result
  }
  return true;
});

// Right — replace with a placeholder instead
const cleaned = messages.map(m => {
  if (m.role === 'tool' && looksLikeError(m.content)) {
    return { ...m, content: '[tool result unavailable]' };
  }
  return m;
});

Failure mode 5: multi-step and stopWhen misconfiguration

Multi-step tool use (where the model calls a tool, sees the result, calls another) needs stop conditions. Without them, you can run indefinitely.

import { stepCountIs } from 'ai';

const result = await generateText({
  model: anthropic('claude-sonnet-4-6'),
  tools: { ... },
  messages,
  stopWhen: stepCountIs(10),  // max 10 tool-use rounds
  // Without this, if the model keeps calling tools, you run forever
  // (or until context overflow)
});

// Custom stop condition
stopWhen: async ({ steps }) => {
  const lastStep = steps[steps.length - 1];
  // Stop if we've spent more than $1 on this request
  const cost = calculateCost(steps);
  return cost > 1.0;
},

Failure mode 6: streaming tool calls with client-side execution

When tools execute on the client (e.g., DOM manipulation, browser APIs), the SDK's streaming protocol handles the round-trip. But if the client-side execution fails, the server-side stream is left waiting. Set a timeout.

const { messages, addToolResult } = useChat({
  api: '/api/chat',
  onToolCall: async ({ toolCall }) => {
    // Client-side tool execution
    if (toolCall.toolName === 'showDialog') {
      try {
        const result = await showDialog(toolCall.args.title);
        return result;
      } catch (error) {
        // Return an error result so the server knows to move on
        return { error: 'Dialog was dismissed' };
      }
    }
  },
});

generateObject and streamObject — the structured output failures

generateObject and streamObject are the SDK's structured output primitives. They take a Zod schema, prompt the model appropriately for whichever provider you're using, and return typed output. Most of the time, they work seamlessly. When they don't, the errors are specific and worth understanding.

NoObjectGeneratedError — the top-level failure

The model returned something that couldn't be coerced into your schema. The error preserves what actually came back so you can debug.

import { generateObject, NoObjectGeneratedError } from 'ai';
import { z } from 'zod';

const schema = z.object({
  name: z.string(),
  age: z.number().min(0).max(150),
  email: z.string().email(),
});

try {
  const { object } = await generateObject({
    model: anthropic('claude-sonnet-4-6'),
    schema,
    prompt: 'Extract user info from: John, thirty years old, john@example.com',
  });
  console.log(object);  // typed as { name: string, age: number, email: string }
} catch (error) {
  if (NoObjectGeneratedError.isInstance(error)) {
    console.error('Object generation failed', {
      cause: error.cause,           // underlying reason
      response: error.response,      // what the model actually returned
      usage: error.usage,            // tokens consumed anyway
      finishReason: error.finishReason,
    });
  }
}

The three most common causes

1. Schema too strict for the input

The schema requires fields the input doesn't contain. The model either invents plausible values (bad) or fails validation (better). Loosen the schema or provide fallbacks.

// Fragile
const schema = z.object({
  name: z.string(),
  age: z.number(),
  email: z.string().email(),  // often missing in real inputs
});

// Robust
const schema = z.object({
  name: z.string(),
  age: z.number().optional(),
  email: z.string().email().optional(),
});

2. Refinement failures

Zod's .refine() and .superRefine() add custom validation. If the model produces output that fails these refinements, you get a validation error even though the shape is correct.

// Refinement that trips silently
const schema = z.object({
  startDate: z.string(),
  endDate: z.string(),
}).refine(
  data => new Date(data.endDate) > new Date(data.startDate),
  { message: 'endDate must be after startDate' }
);

// Model might produce dates in wrong order
// Options:
// 1. Include refinement rules in the prompt so the model knows
// 2. Post-process to swap if wrong order
// 3. Accept and repair after the fact

3. Provider limitations

Not all providers support all Zod features equally. OpenAI's strict mode requires additionalProperties: false everywhere. Gemini can't handle all string formats. Claude's tool-based structured output has softer guarantees.

// This works on Claude and Gemini, may fail on OpenAI strict mode
const schema = z.record(z.string(), z.number());  // dynamic keys

// Safer — explicit keys
const schema = z.object({
  known_key_1: z.number().optional(),
  known_key_2: z.number().optional(),
});

The mode parameter matters

// Three modes for generateObject
generateObject({
  model,
  schema,
  prompt,
  mode: 'auto',   // default — SDK picks the best for the provider
  // 'json'       — provider's JSON mode
  // 'tool'       — always use tool_use pattern
});

For OpenAI, 'json' uses their native structured output (strongest guarantee). For Claude, 'tool' uses forced tool_use (idiomatic). For Gemini, 'json' uses responseSchema. 'auto' picks appropriately — but if you're seeing repeated failures, try switching modes explicitly.

streamObject — incremental structured output

const { partialObjectStream } = streamObject({
  model: openai('gpt-5-6'),
  schema,
  prompt: userInput,
});

// Each yielded value is a partial version of the schema
for await (const partial of partialObjectStream) {
  // partial has type Partial>
  updateUI(partial);
}

// Validation happens at the end; intermediate partials 
// may not satisfy required fields.

Retry with feedback for structured output

If generation fails validation, retry with the error as context. The model can often self-correct.

async function generateWithRepair(prompt: string, maxAttempts = 3) {
  let lastError: unknown;
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      const { object } = await generateObject({
        model: anthropic('claude-sonnet-4-6'),
        schema,
        prompt: attempt === 0 
          ? prompt 
          : `${prompt}\n\nPrevious attempt failed validation: ${
              (lastError as Error).message
            }. Please correct.`,
      });
      return object;
    } catch (error) {
      lastError = error;
      if (!NoObjectGeneratedError.isInstance(error)) throw error;
    }
  }
  throw lastError;
}

The server-client boundary — RSC and edge runtime gotchas

Next.js React Server Components (RSC), the edge runtime, and Vercel's various compute environments all interact with the AI SDK in ways that produce their own class of errors. Most of these are configuration issues rather than runtime bugs, but they manifest as runtime crashes.

Server actions vs API routes

// Server action (Next.js App Router)
'use server';
import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

export async function askAI(prompt: string) {
  const { text } = await generateText({
    model: anthropic('claude-sonnet-4-6'),
    prompt,
  });
  return text;
}

// API route (also works)
// app/api/chat/route.ts
export async function POST(request: Request) {
  const { messages } = await request.json();
  const result = streamText({
    model: anthropic('claude-sonnet-4-6'),
    messages,
  });
  return result.toDataStreamResponse();
}

Common failure: streaming in server actions

Server actions cannot stream directly in the way API routes can. If you need streaming, use an API route. If you use server actions for AI, they return the full result at once.

// Wrong — trying to stream from a server action
'use server';
export async function chat(messages) {
  const result = streamText({ ... });
  return result.textStream;  // Won't work — streams don't cross the boundary
}

// Right — use useObject for streaming structured output from server actions
// Or use an API route for text streaming

Edge runtime restrictions

Vercel Edge Functions and similar edge runtimes have restrictions: no Node.js APIs (fs, crypto's default provider, some Node modules). Most provider SDKs work on edge, but not all.

// Configure the runtime explicitly
export const runtime = 'edge';   // or 'nodejs'

// Watch for: modules that use fs, path, or Node-only crypto
// If a provider SDK requires Node APIs, either:
// 1. Switch runtime to 'nodejs' (slower cold starts)
// 2. Use a different provider or the fetch-based variant

// Most @ai-sdk providers work on edge as of v5
// If you get "Module not found" errors on edge, check provider docs

The API key isn't loading

LoadAPIKeyError fires when the SDK can't find your API key. Root causes vary by environment.

// Local dev — .env.local
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_GENERATIVE_AI_API_KEY=...

// Vercel deployment — set in project settings > Environment Variables
// Make sure the variable is available in the correct environments
// (Production, Preview, Development)

// Explicit override for provider clients
const anthropic = createAnthropic({
  apiKey: process.env.MY_CUSTOM_KEY,  // if the env var name differs
});

// Common error:
// AI_LoadAPIKeyError: Anthropic API key is missing.
// Solution: check env var name, deployment env, and that
// the variable is exposed to the specific runtime.

Client-side data leakage

The AI SDK is server-side by default. Never call generateText or streamText from a client component — your API key ends up in the client bundle.

// WRONG — 'use client' with direct SDK call
'use client';
import { generateText } from 'ai';  // BAD: bundles API key to client

// RIGHT — use hooks or fetch from client, do generation on server
'use client';
import { useChat } from '@ai-sdk/react';  // safe: hook fetches from your API

Hydration mismatches with streaming responses

If you render server-generated AI content in a component that's also client-hydrated, the streamed values can create hydration mismatches. Wrap streaming areas in <Suspense> or use client-only rendering.

import { Suspense } from 'react';

export default function Page() {
  return (
    

      
My AI App
      Loading AI response...
}>