ai 6.0.30 → 6.0.32

package/docs/09-troubleshooting/06-timeout-on-vercel.mdx

@@ -0,0 +1,60 @@
+---
+title: Getting Timeouts When Deploying on Vercel
+description: Learn how to fix timeouts and cut off responses when deploying to Vercel.
+---
+
+# Getting Timeouts When Deploying on Vercel
+
+## Issue
+
+Streaming with the AI SDK works in my local development environment.
+However, when I'm deploying to Vercel, longer responses get chopped off in the UI and I'm seeing timeouts in the Vercel logs or I'm seeing the error: `Uncaught (in promise) Error: Connection closed`.
+
+## Solution
+
+With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute), the default function duration is now **5 minutes (300 seconds)** across all plans. This should be sufficient for most streaming applications.
+
+If you need to extend the timeout for longer-running processes, you can increase the `maxDuration` setting:
+
+### Next.js (App Router)
+
+Add the following to your route file or the page you are calling your Server Action from:
+
+```tsx
+export const maxDuration = 600;
+```
+
+<Note>
+  Setting `maxDuration` above 300 seconds requires a Pro or Enterprise plan.
+</Note>
+
+### Other Frameworks
+
+For other frameworks, you can set timeouts in your `vercel.json` file:
+
+```json
+{
+  "functions": {
+    "api/chat/route.ts": {
+      "maxDuration": 600
+    }
+  }
+}
+```
+
+<Note>
+  Setting `maxDuration` above 300 seconds requires a Pro or Enterprise plan.
+</Note>
+
+### Maximum Duration Limits
+
+The maximum duration you can set depends on your Vercel plan:
+
+- **Hobby**: Up to 300 seconds (5 minutes)
+- **Pro**: Up to 800 seconds (~13 minutes)
+- **Enterprise**: Up to 800 seconds (~13 minutes)
+
+## Learn more
+
+- [Fluid Compute Default Settings](https://vercel.com/docs/fluid-compute#default-settings-by-plan)
+- [Configuring Maximum Duration for Vercel Functions](https://vercel.com/docs/functions/configuring-functions/duration)

package/docs/09-troubleshooting/07-unclosed-streams.mdx

@@ -0,0 +1,34 @@
+---
+title: Unclosed Streams
+description: Troubleshooting errors related to unclosed streams.
+---
+
+# Unclosed Streams
+
+Sometimes streams are not closed properly, which can lead to unexpected behavior. The following are some common issues that can occur when streams are not closed properly.
+
+## Issue
+
+The streamable UI has been slow to update.
+
+## Solution
+
+This happens when you create a streamable UI using [`createStreamableUI`](/docs/reference/ai-sdk-rsc/create-streamable-ui) and fail to close the stream.
+In order to fix this, you must ensure you close the stream by calling the [`.done()`](/docs/reference/ai-sdk-rsc/create-streamable-ui#done) method.
+This will ensure the stream is closed.
+
+```tsx file='app/actions.tsx'
+import { createStreamableUI } from '@ai-sdk/rsc';
+
+const submitMessage = async () => {
+  'use server';
+
+  const stream = createStreamableUI('1');
+
+  stream.update('2');
+  stream.append('3');
+  stream.done('4'); // [!code ++]
+
+  return stream.value;
+};
+```

package/docs/09-troubleshooting/08-use-chat-failed-to-parse-stream.mdx

@@ -0,0 +1,26 @@
+---
+title: useChat Failed to Parse Stream
+description: Troubleshooting errors related to the Use Chat Failed to Parse Stream error.
+---
+
+# `useChat` "Failed to Parse Stream String" Error
+
+## Issue
+
+I am using [`useChat`](/docs/reference/ai-sdk-ui/use-chat) or [`useCompletion`](/docs/reference/ai-sdk-ui/use-completion), and I am getting a `"Failed to parse stream string. Invalid code"` error. I am using version `3.0.20` or newer of the AI SDK.
+
+## Background
+
+The AI SDK has switched to the stream data protocol in version `3.0.20`.
+[`useChat`](/docs/reference/ai-sdk-ui/use-chat) and [`useCompletion`](/docs/reference/ai-sdk-ui/use-completion) expect stream parts that support data, tool calls, etc.
+What you see is a failure to parse the stream.
+This can be caused by using an older version of the AI SDK in the backend, by providing a text stream using a custom provider, or by using a raw LangChain stream result.
+
+## Solution
+
+You can switch [`useChat`](/docs/reference/ai-sdk-ui/use-chat) and [`useCompletion`](/docs/reference/ai-sdk-ui/use-completion) to raw text stream processing with the [`streamProtocol`](/docs/reference/ai-sdk-ui/use-completion#stream-protocol) parameter.
+Set it to `text` as follows:
+
+```tsx
+const { messages, append } = useChat({ streamProtocol: 'text' });
+```

package/docs/09-troubleshooting/09-client-stream-error.mdx

@@ -0,0 +1,25 @@
+---
+title: Server Action Plain Objects Error
+description: Troubleshooting errors related to using AI SDK Core functions with Server Actions.
+---
+
+# "Only plain objects can be passed from client components" Server Action Error
+
+## Issue
+
+I am using [`streamText`](/docs/reference/ai-sdk-core/stream-text) or [`streamObject`](/docs/reference/ai-sdk-core/stream-object) with Server Actions, and I am getting a `"only plain objects and a few built ins can be passed from client components"` error.
+
+## Background
+
+This error occurs when you're trying to return a non-serializable object from a Server Action to a Client Component. The streamText function likely returns an object with methods or complex structures that can't be directly serialized and passed to the client.
+
+## Solution
+
+To fix this issue, you need to ensure that you're only returning serializable data from your Server Action. Here's how you can modify your approach:
+
+1. Instead of returning the entire result object from streamText, extract only the necessary serializable data.
+2. Use the [`createStreamableValue`](/docs/reference/ai-sdk-rsc/create-streamable-value) function to create a streamable value that can be safely passed to the client.
+
+Here's an example that demonstrates how to implement this solution: [Streaming Text Generation](/examples/next-app/basics/streaming-text-generation).
+
+This approach ensures that only serializable data (the text) is passed to the client, avoiding the "only plain objects" error.

package/docs/09-troubleshooting/10-use-chat-tools-no-response.mdx

@@ -0,0 +1,32 @@
+---
+title: useChat No Response
+description: Troubleshooting errors related to the Use Chat Failed to Parse Stream error.
+---
+
+# `useChat` No Response
+
+## Issue
+
+I am using [`useChat`](/docs/reference/ai-sdk-ui/use-chat).
+When I log the incoming messages on the server, I can see the tool call and the tool result, but the model does not respond with anything.
+
+## Solution
+
+To resolve this issue, convert the incoming messages to the `ModelMessage` format using the [`convertToModelMessages`](/docs/reference/ai-sdk-ui/convert-to-model-messages) function.
+
+```tsx highlight="9"
+import { openai } from '@ai-sdk/openai';
+import { convertToModelMessages, streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```

package/docs/09-troubleshooting/11-use-chat-custom-request-options.mdx

@@ -0,0 +1,149 @@
+---
+title: Custom headers, body, and credentials not working with useChat
+description: Troubleshooting errors related to custom request configuration in useChat hook
+---
+
+# Custom headers, body, and credentials not working with useChat
+
+## Issue
+
+When using the `useChat` hook, custom request options like headers, body fields, and credentials configured directly on the hook are not being sent with the request:
+
+```tsx
+// These options are not sent with the request
+const { messages, sendMessage } = useChat({
+  headers: {
+    Authorization: 'Bearer token123',
+  },
+  body: {
+    user_id: '123',
+  },
+  credentials: 'include',
+});
+```
+
+## Background
+
+The `useChat` hook has changed its API for configuring request options. Direct options like `headers`, `body`, and `credentials` on the hook itself are no longer supported. Instead, you need to use the `transport` configuration with `DefaultChatTransport` or pass options at the request level.
+
+## Solution
+
+There are three ways to properly configure request options with `useChat`:
+
+### Option 1: Request-Level Configuration (Recommended for Dynamic Values)
+
+For dynamic values that change over time, the recommended approach is to pass options when calling `sendMessage`:
+
+```tsx
+const { messages, sendMessage } = useChat();
+
+// Send options with each message
+sendMessage(
+  { text: input },
+  {
+    headers: {
+      Authorization: `Bearer ${getAuthToken()}`, // Dynamic auth token
+      'X-Request-ID': generateRequestId(),
+    },
+    body: {
+      temperature: 0.7,
+      max_tokens: 100,
+      user_id: getCurrentUserId(), // Dynamic user ID
+      sessionId: getCurrentSessionId(), // Dynamic session
+    },
+  },
+);
+```
+
+This approach ensures that the most up-to-date values are always sent with each request.
+
+### Option 2: Hook-Level Configuration with Static Values
+
+For static values that don't change during the component lifecycle, use the `DefaultChatTransport`:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    headers: {
+      'X-API-Version': 'v1', // Static API version
+      'X-App-ID': 'my-app', // Static app identifier
+    },
+    body: {
+      model: 'gpt-5.1', // Default model
+      stream: true, // Static configuration
+    },
+    credentials: 'include', // Static credentials policy
+  }),
+});
+```
+
+### Option 3: Hook-Level Configuration with Resolvable Functions
+
+If you need dynamic values at the hook level, you can use functions that return configuration values. However, request-level configuration is generally preferred for better reliability:
+
+```tsx
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    headers: () => ({
+      Authorization: `Bearer ${getAuthToken()}`,
+      'X-User-ID': getCurrentUserId(),
+    }),
+    body: () => ({
+      sessionId: getCurrentSessionId(),
+      preferences: getUserPreferences(),
+    }),
+    credentials: () => (isAuthenticated() ? 'include' : 'same-origin'),
+  }),
+});
+```
+
+<Note>
+  For component state that changes over time, request-level configuration
+  (Option 1) is recommended. If using hook-level functions, consider using
+  `useRef` to store current values and reference `ref.current` in your
+  configuration function.
+</Note>
+
+### Combining Hook and Request Level Options
+
+Request-level options take precedence over hook-level options:
+
+```tsx
+// Hook-level default configuration
+const { messages, sendMessage } = useChat({
+  transport: new DefaultChatTransport({
+    api: '/api/chat',
+    headers: {
+      'X-API-Version': 'v1',
+    },
+    body: {
+      model: 'gpt-5.1',
+    },
+  }),
+});
+
+// Override or add options per request
+sendMessage(
+  { text: input },
+  {
+    headers: {
+      'X-API-Version': 'v2', // This overrides the hook-level header
+      'X-Request-ID': '123', // This is added
+    },
+    body: {
+      model: 'gpt-5-mini', // This overrides the hook-level body field
+      temperature: 0.5, // This is added
+    },
+  },
+);
+```
+
+For more details on request configuration, see the [Request Configuration](/docs/ai-sdk-ui/chatbot#request-configuration) documentation.

package/docs/09-troubleshooting/12-typescript-performance-zod.mdx

@@ -0,0 +1,46 @@
+---
+title: TypeScript performance issues with Zod and AI SDK 5
+description: Troubleshooting TypeScript server crashes and slow performance when using Zod with AI SDK 5
+---
+
+# TypeScript performance issues with Zod and AI SDK 5
+
+## Issue
+
+When using the AI SDK 5 with Zod, you may experience:
+
+- TypeScript server crashes or hangs
+- Extremely slow type checking in files that import AI SDK functions
+- Error messages like "Type instantiation is excessively deep and possibly infinite"
+- IDE becoming unresponsive when working with AI SDK code
+
+## Background
+
+The AI SDK 5 has specific compatibility requirements with Zod versions. When importing Zod using the standard import path (`import { z } from 'zod'`), TypeScript's type inference can become excessively complex, leading to performance degradation or crashes.
+
+## Solution
+
+### Upgrade Zod to 4.1.8 or Later
+
+The primary solution is to upgrade to Zod version 4.1.8 or later, which includes a fix for this module resolution issue:
+
+```bash
+pnpm add zod@^4.1.8
+```
+
+This version resolves the underlying problem where different module resolution settings were causing TypeScript to load the same Zod declarations twice, leading to expensive structural comparisons.
+
+### Alternative: Update TypeScript Configuration
+
+If upgrading Zod isn't possible, you can update your `tsconfig.json` to use `moduleResolution: "nodenext"`:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "nodenext"
+    // ... other options
+  }
+}
+```
+
+This resolves the TypeScript performance issues while allowing you to continue using the standard Zod import.

package/docs/09-troubleshooting/12-use-chat-an-error-occurred.mdx

@@ -0,0 +1,59 @@
+---
+title: useChat "An error occurred"
+description: Troubleshooting errors related to the "An error occurred" error in useChat.
+---
+
+# `useChat` "An error occurred"
+
+## Issue
+
+I am using [`useChat`](/docs/reference/ai-sdk-ui/use-chat) and I get the error "An error occurred".
+
+## Background
+
+Error messages from `streamText` are masked by default when using `toDataStreamResponse` for security reasons (secure-by-default).
+This prevents leaking sensitive information to the client.
+
+## Solution
+
+To forward error details to the client or to log errors, use the `getErrorMessage` function when calling `toDataStreamResponse`.
+
+```tsx
+export function errorHandler(error: unknown) {
+  if (error == null) {
+    return 'unknown error';
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return JSON.stringify(error);
+}
+```
+
+```tsx
+const result = streamText({
+  // ...
+});
+
+return result.toUIMessageStreamResponse({
+  getErrorMessage: errorHandler,
+});
+```
+
+In case you are using `createDataStreamResponse`, you can use the `onError` function when calling `toDataStreamResponse`:
+
+```tsx
+const response = createDataStreamResponse({
+  // ...
+  async execute(dataStream) {
+    // ...
+  },
+  onError: errorHandler,
+});
+```

package/docs/09-troubleshooting/13-repeated-assistant-messages.mdx

@@ -0,0 +1,73 @@
+---
+title: Repeated assistant messages in useChat
+description: Troubleshooting duplicate assistant messages when using useChat with streamText
+---
+
+# Repeated assistant messages in useChat
+
+## Issue
+
+When using `useChat` with `streamText` on the server, the assistant's messages appear duplicated in the UI - showing both the previous message and the new message, or showing the same message multiple times. This can occur when using tool calls or complex message flows.
+
+```tsx
+// Server-side code that may experience assistant message duplication on the client
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: 'openai/gpt-5-mini',
+    messages: await convertToModelMessages(messages),
+    tools: {
+      weather: {
+        description: 'Get the weather for a location',
+        parameters: z.object({
+          location: z.string(),
+        }),
+        execute: async ({ location }) => {
+          return { temperature: 72, condition: 'sunny' };
+        },
+      },
+    },
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+## Background
+
+The duplication occurs because `toUIMessageStreamResponse` generates new message IDs for each new message.
+
+## Solution
+
+Pass the original messages array to `toUIMessageStreamResponse` using the `originalMessages` option. By passing `originalMessages`, the method can reuse existing message IDs instead of generating new ones, ensuring the client properly updates existing messages rather than creating duplicates.
+
+```tsx
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: 'openai/gpt-5-mini',
+    messages: await convertToModelMessages(messages),
+    tools: {
+      weather: {
+        description: 'Get the weather for a location',
+        parameters: z.object({
+          location: z.string(),
+        }),
+        execute: async ({ location }) => {
+          return { temperature: 72, condition: 'sunny' };
+        },
+      },
+    },
+  });
+
+  return result.toUIMessageStreamResponse({
+    originalMessages: messages, // Pass the original messages here
+    generateMessageId: generateId,
+    onFinish: ({ messages }) => {
+      saveChat({ id, messages });
+    },
+  });
+}
+```

package/docs/09-troubleshooting/14-stream-abort-handling.mdx

@@ -0,0 +1,73 @@
+---
+title: onFinish not called when stream is aborted
+description: Troubleshooting onFinish callback not executing when streams are aborted with toUIMessageStreamResponse
+---
+
+# onFinish not called when stream is aborted
+
+## Issue
+
+When using `toUIMessageStreamResponse` with an `onFinish` callback, the callback may not execute when the stream is aborted. This happens because the abort handler immediately terminates the response, preventing the `onFinish` callback from being triggered.
+
+```tsx
+// Server-side code where onFinish isn't called on abort
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+    abortSignal: req.signal,
+  });
+
+  return result.toUIMessageStreamResponse({
+    onFinish: async ({ isAborted }) => {
+      // This isn't called when the stream is aborted!
+      if (isAborted) {
+        console.log('Stream was aborted');
+        // Handle abort-specific cleanup
+      } else {
+        console.log('Stream completed normally');
+        // Handle normal completion
+      }
+    },
+  });
+}
+```
+
+## Background
+
+When a stream is aborted, the response is immediately terminated. Without proper handling, the `onFinish` callback has no chance to execute, preventing important cleanup operations like saving partial results or logging abort events.
+
+## Solution
+
+Add `consumeStream` to the `toUIMessageStreamResponse` configuration. This ensures that abort events are properly captured and forwarded to the `onFinish` callback, allowing it to execute even when the stream is aborted.
+
+```tsx
+// other imports...
+import { consumeStream } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: __MODEL__,
+    messages: await convertToModelMessages(messages),
+    abortSignal: req.signal,
+  });
+
+  return result.toUIMessageStreamResponse({
+    onFinish: async ({ isAborted }) => {
+      // Now this WILL be called even when aborted!
+      if (isAborted) {
+        console.log('Stream was aborted');
+        // Handle abort-specific cleanup
+      } else {
+        console.log('Stream completed normally');
+        // Handle normal completion
+      }
+    },
+    consumeSseStream: consumeStream, // This enables onFinish to be called on abort
+  });
+}
+```

package/docs/09-troubleshooting/14-tool-calling-with-structured-outputs.mdx

@@ -0,0 +1,48 @@
+---
+title: Tool calling with generateObject and streamObject
+description: Troubleshooting tool calling when combined with generateObject and streamObject
+---
+
+# Tool calling with generateObject and streamObject (structured outputs)
+
+## Issue
+
+You may want to combine tool calling with structured output generation. While `generateObject` and `streamObject` are designed specifically for structured outputs, they don't support tool calling.
+
+## Background
+
+To use tool calling with structured outputs, use `generateText` or `streamText` with the `output` option.
+
+**Important**: When using `output` with tool calling, the structured output generation counts as an additional step in the execution flow.
+
+## Solution
+
+When using `output` with tool calling, adjust your `stopWhen` condition to account for the additional step required for structured output generation:
+
+```tsx
+const result = await generateText({
+  model: __MODEL__,
+  output: Output.object({
+    schema: z.object({
+      summary: z.string(),
+      sentiment: z.enum(['positive', 'neutral', 'negative']),
+    }),
+  }),
+  tools: {
+    analyze: tool({
+      description: 'Analyze data',
+      inputSchema: z.object({
+        data: z.string(),
+      }),
+      execute: async ({ data }) => {
+        return { result: 'analyzed' };
+      }),
+    },
+  },
+  // Add at least 1 to your intended step count to account for structured output
+  stopWhen: stepCountIs(3), // Now accounts for: tool call + tool result + structured output
+  prompt: 'Analyze the data and provide a summary',
+});
+```
+
+For more information about using structured outputs with `generateText` and `streamText` see [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data#structured-outputs-with-generatetext-and-streamtext).

package/docs/09-troubleshooting/15-abort-breaks-resumable-streams.mdx

@@ -0,0 +1,55 @@
+---
+title: Abort breaks resumable streams
+description: Troubleshooting stream resumption failures when using abort functionality
+---
+
+# Abort breaks resumable streams
+
+## Issue
+
+When using `useChat` with `resume: true` for stream resumption, the abort functionality breaks. Closing a tab, refreshing the page, or calling the `stop()` function will trigger an abort signal that interferes with the resumption mechanism, preventing streams from being properly resumed.
+
+```tsx
+// This configuration will cause conflicts
+const { messages, stop } = useChat({
+  id: chatId,
+  resume: true, // Stream resumption enabled
+});
+
+// Closing the tab will trigger abort and stop resumption
+```
+
+## Background
+
+When a page is closed or refreshed, the browser automatically sends an abort signal, which breaks the resumption flow.
+
+## Current limitations
+
+We're aware of this incompatibility and are exploring solutions. **In the meantime, please choose either stream resumption or abort functionality based on your application's requirements**, but not both.
+
+### Option 1: Use stream resumption without abort
+
+If you need to support long-running generations that persist across page reloads:
+
+```tsx
+const { messages, sendMessage } = useChat({
+  id: chatId,
+  resume: true,
+});
+```
+
+### Option 2: Use abort without stream resumption
+
+If you need to allow users to stop streams manually:
+
+```tsx
+const { messages, sendMessage, stop } = useChat({
+  id: chatId,
+  resume: false, // Disable stream resumption (default behaviour)
+});
+```
+
+## Related
+
+- [Chatbot Resume Streams](/docs/ai-sdk-ui/chatbot-resume-streams)
+- [Stopping Streams](/docs/advanced/stopping-streams)