ai 6.0.31 → 6.0.32

package/docs/09-troubleshooting/15-stream-text-not-working.mdx

@@ -0,0 +1,33 @@
+---
+title: streamText fails silently
+description: Troubleshooting errors related to the streamText function not working.
+---
+
+# `streamText` is not working
+
+## Issue
+
+I am using [`streamText`](/docs/reference/ai-sdk-core/stream-text) function, and it does not work.
+It does not throw any errors and the stream is only containing error parts.
+
+## Background
+
+`streamText` immediately starts streaming to enable sending data without waiting for the model.
+Errors become part of the stream and are not thrown to prevent e.g. servers from crashing.
+
+## Solution
+
+To log errors, you can provide an `onError` callback that is triggered when an error occurs.
+
+```tsx highlight="6-8"
+import { streamText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Invent a new holiday and describe its traditions.',
+  onError({ error }) {
+    console.error(error); // your error logging logic here
+  },
+});
+```

package/docs/09-troubleshooting/16-streaming-status-delay.mdx

@@ -0,0 +1,63 @@
+---
+title: Streaming Status Shows But No Text Appears
+description: Why useChat shows "streaming" status without any visible content
+---
+
+# Streaming Status Shows But No Text Appears
+
+## Issue
+
+When using `useChat`, the status changes to "streaming" immediately, but no text appears for several seconds.
+
+## Background
+
+The status changes to "streaming" as soon as the connection to the server is established and streaming begins - this includes metadata streaming, not just the LLM's generated tokens.
+
+## Solution
+
+Create a custom loading state that checks if the last assistant message actually contains content:
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+
+export default function Page() {
+  const { messages, status } = useChat();
+
+  const lastMessage = messages.at(-1);
+
+  const showLoader =
+    status === 'streaming' &&
+    lastMessage?.role === 'assistant' &&
+    lastMessage?.parts?.length === 0;
+
+  return (
+    <>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.role === 'user' ? 'User: ' : 'AI: '}
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? <span key={index}>{part.text}</span> : null,
+          )}
+        </div>
+      ))}
+
+      {showLoader && <div>Loading...</div>}
+    </>
+  );
+}
+```
+
+You can also check for specific part types if you're waiting for something specific:
+
+```tsx
+const showLoader =
+  status === 'streaming' &&
+  lastMessage?.role === 'assistant' &&
+  !lastMessage?.parts?.some(part => part.type === 'text');
+```
+
+## Related Issues
+
+- [GitHub Issue #7586](https://github.com/vercel/ai/issues/7586)

package/docs/09-troubleshooting/17-use-chat-stale-body-data.mdx

@@ -0,0 +1,141 @@
+---
+title: Stale body values with useChat
+description: Troubleshooting stale values when passing information via the body parameter of useChat
+---
+
+# Stale body values with useChat
+
+## Issue
+
+When using `useChat` and passing dynamic information via the `body` parameter at the hook level, the data remains stale and only reflects the value from the initial component render. This occurs because the body configuration is captured once when the hook is initialized and doesn't update with subsequent component re-renders.
+
+```tsx
+// Problematic code - body data will be stale
+export default function Chat() {
+  const [temperature, setTemperature] = useState(0.7);
+  const [userId, setUserId] = useState('user123');
+
+  // This body configuration is captured once and won't update
+  const { messages, sendMessage } = useChat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+      body: {
+        temperature, // Always the initial value (0.7)
+        userId, // Always the initial value ('user123')
+      },
+    }),
+  });
+
+  // Even if temperature or userId change, the body in requests will still use initial values
+  return (
+    <div>
+      <input
+        type="range"
+        value={temperature}
+        onChange={e => setTemperature(parseFloat(e.target.value))}
+      />
+      {/* Chat UI */}
+    </div>
+  );
+}
+```
+
+## Background
+
+The hook-level body configuration is evaluated once during the initial render and doesn't re-evaluate when component state changes.
+
+## Solution
+
+Pass dynamic variables via the second argument of the `sendMessage` function instead of at the hook level. Request-level options are evaluated on each call and take precedence over hook-level options.
+
+```tsx
+export default function Chat() {
+  const [temperature, setTemperature] = useState(0.7);
+  const [userId, setUserId] = useState('user123');
+  const [input, setInput] = useState('');
+
+  const { messages, sendMessage } = useChat({
+    // Static configuration only
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+    }),
+  });
+
+  return (
+    <div>
+      <input
+        type="range"
+        value={temperature}
+        onChange={e => setTemperature(parseFloat(e.target.value))}
+      />
+
+      <form
+        onSubmit={event => {
+          event.preventDefault();
+          if (input.trim()) {
+            // Pass dynamic values as request-level options
+            sendMessage(
+              { text: input },
+              {
+                body: {
+                  temperature, // Current value at request time
+                  userId, // Current value at request time
+                },
+              },
+            );
+            setInput('');
+          }
+        }}
+      >
+        <input value={input} onChange={e => setInput(e.target.value)} />
+      </form>
+    </div>
+  );
+}
+```
+
+### Alternative: Dynamic Hook-Level Configuration
+
+If you need hook-level configuration that responds to changes, you can use functions that return configuration values. However, for component state, you'll need to use `useRef` to access current values:
+
+```tsx
+export default function Chat() {
+  const temperatureRef = useRef(0.7);
+
+  const { messages, sendMessage } = useChat({
+    transport: new DefaultChatTransport({
+      api: '/api/chat',
+      body: () => ({
+        temperature: temperatureRef.current, // Access via ref.current
+        sessionId: getCurrentSessionId(), // Function calls work directly
+      }),
+    }),
+  });
+
+  // ...
+}
+```
+
+**Recommendation:** Request-level configuration is simpler and more reliable for component state. Use it whenever you need to pass dynamic values that change during the component lifecycle.
+
+### Server-side handling
+
+On your server side, retrieve the custom fields by destructuring the request body:
+
+```tsx
+// app/api/chat/route.ts
+export async function POST(req: Request) {
+  const { messages, temperature, userId } = await req.json();
+
+  const result = streamText({
+    model: 'openai/gpt-5-mini',
+    messages: await convertToModelMessages(messages),
+    temperature, // Use the dynamic temperature from the request
+    // ... other configuration
+  });
+
+  return result.toUIMessageStreamResponse();
+}
+```
+
+For more information, see [chatbot request configuration documentation](/docs/ai-sdk-ui/chatbot#request-configuration).

package/docs/09-troubleshooting/18-ontoolcall-type-narrowing.mdx

@@ -0,0 +1,66 @@
+---
+title: Type Error with onToolCall
+description: How to handle TypeScript type errors when using the onToolCall callback
+---
+
+# Type Error with onToolCall
+
+When using the `onToolCall` callback with TypeScript, you may encounter type errors when trying to pass tool properties directly to `addToolOutput`.
+
+## Problem
+
+TypeScript cannot automatically narrow the type of `toolCall.toolName` when you have both static and dynamic tools, leading to type errors:
+
+```tsx
+// ❌ This causes a TypeScript error
+const { messages, sendMessage, addToolOutput } = useChat({
+  async onToolCall({ toolCall }) {
+    addToolOutput({
+      tool: toolCall.toolName, // Type 'string' is not assignable to type '"yourTool" | "yourOtherTool"'
+      toolCallId: toolCall.toolCallId,
+      output: someOutput,
+    });
+  },
+});
+```
+
+The error occurs because:
+
+- Static tools have specific literal types for their names (e.g., `"getWeatherInformation"`)
+- Dynamic tools have `toolName` as a generic `string`
+- TypeScript can't guarantee that `toolCall.toolName` matches your specific tool names
+
+## Solution
+
+Check if the tool is dynamic first to enable proper type narrowing:
+
+```tsx
+// ✅ Correct approach with type narrowing
+const { messages, sendMessage, addToolOutput } = useChat({
+  async onToolCall({ toolCall }) {
+    // Check if it's a dynamic tool first
+    if (toolCall.dynamic) {
+      return;
+    }
+
+    // Now TypeScript knows this is a static tool with the correct type
+    addToolOutput({
+      tool: toolCall.toolName, // No type error!
+      toolCallId: toolCall.toolCallId,
+      output: someOutput,
+    });
+  },
+});
+```
+
+<Note>
+  If you're still using the deprecated `addToolResult` method, this solution
+  applies the same way. Consider migrating to `addToolOutput` for consistency
+  with the latest API.
+</Note>
+
+## Related
+
+- [Chatbot Tool Usage](/docs/ai-sdk-ui/chatbot-tool-usage)
+- [Dynamic Tools](/docs/reference/ai-sdk-core/dynamic-tool)
+- [useChat Reference](/docs/reference/ai-sdk-ui/use-chat)

package/docs/09-troubleshooting/19-unsupported-model-version.mdx

@@ -0,0 +1,50 @@
+---
+title: Unsupported model version error
+description: Troubleshooting the AI_UnsupportedModelVersionError when migrating to AI SDK 5
+---
+
+# Unsupported model version error
+
+## Issue
+
+When migrating to AI SDK 5, you might encounter an error stating that your model uses an unsupported version:
+
+```
+AI_UnsupportedModelVersionError: Unsupported model version v1 for provider "ollama.chat" and model "gamma3:4b".
+AI SDK 5 only supports models that implement specification version "v2".
+```
+
+This error occurs because the version of the provider package you're using implements the older (v1) model specification.
+
+## Background
+
+AI SDK 5 requires all provider packages to implement specification version "v2". When you upgrade to AI SDK 5 but don't update your provider packages to compatible versions, they continue using the older "v1" specification, causing this error.
+
+## Solution
+
+### Update provider packages to AI SDK 5 compatible versions
+
+Update all your `@ai-sdk/*` provider packages to compatible version `2.0.0` or later. These versions implement the v2 specification required by AI SDK 5.
+
+```bash
+pnpm install ai@latest @ai-sdk/openai@latest @ai-sdk/anthropic@latest
+```
+
+For AI SDK 5 compatibility, you need:
+
+- `ai` package: `5.0.0` or later
+- `@ai-sdk/*` packages: `2.0.0` or later (for example, `@ai-sdk/openai`, `@ai-sdk/anthropic`, `@ai-sdk/google`)
+- `@ai-sdk/provider` package: `2.0.0` or later
+- `zod` package: `4.1.8` or later
+
+### Check provider compatibility
+
+If you're using a third-party or custom provider, verify that it has been updated to support AI SDK 5. Not all providers may have v2-compatible versions available yet.
+
+To check if a provider supports AI SDK 5:
+
+1. Check the provider's package.json for `@ai-sdk/provider` peer dependency version `2.0.0` or later
+2. Review the provider's changelog or migration guide
+3. Check the provider's repository for AI SDK 5 support
+
+For more information on migrating to AI SDK 5, see the [AI SDK 5.0 migration guide](/docs/migration-guides/migration-guide-5-0).

package/docs/09-troubleshooting/20-no-object-generated-content-filter.mdx

@@ -0,0 +1,72 @@
+---
+title: Object generation failed with OpenAI
+description: Troubleshooting NoObjectGeneratedError with finish-reason content-filter caused by incompatible Zod schema types when using OpenAI structured outputs
+---
+
+# Object generation failed with OpenAI
+
+## Issue
+
+When using `generateObject` or `streamObject` with OpenAI's structured output generation, you may encounter a `NoObjectGeneratedError` with the finish reason `content-filter`. This error occurs when your Zod schema contains incompatible types that OpenAI's structured output feature cannot process.
+
+```typescript
+// Problematic code - incompatible schema types
+import { generateObject } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const result = await generateObject({
+  model: openai('gpt-4o-2024-08-06'),
+  schema: z.object({
+    name: z.string().nullish(), // ❌ .nullish() is not supported
+    email: z.string().optional(), // ❌ .optional() is not supported
+    age: z.number().nullable(), // ✅ .nullable() is supported
+  }),
+  prompt: 'Generate a user profile',
+});
+
+// Error: NoObjectGeneratedError: No object generated.
+// Finish reason: content-filter
+```
+
+## Background
+
+OpenAI's structured output generation uses JSON Schema under the hood and has specific requirements for schema compatibility. The Zod methods `.nullish()` and `.optional()` generate JSON Schema patterns that are incompatible with OpenAI's implementation, causing the model to reject the schema and return a content-filter finish reason.
+
+## Solution
+
+Replace `.nullish()` and `.optional()` with `.nullable()` in your Zod schemas when using structured output generation with OpenAI models.
+
+```typescript
+import { generateObject } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+// Correct approach - use .nullable()
+const result = await generateObject({
+  model: openai('gpt-4o-2024-08-06'),
+  schema: z.object({
+    name: z.string().nullable(), // ✅ Use .nullable() instead of .nullish()
+    email: z.string().nullable(), // ✅ Use .nullable() instead of .optional()
+    age: z.number().nullable(),
+  }),
+  prompt: 'Generate a user profile',
+});
+
+console.log(result.object);
+// { name: "John Doe", email: "john@example.com", age: 30 }
+// or { name: null, email: null, age: 25 }
+```
+
+### Schema Type Comparison
+
+| Zod Type      | Compatible | JSON Schema Behavior                                   |
+| ------------- | ---------- | ------------------------------------------------------ |
+| `.nullable()` | ✅ Yes     | Allows `null` or the specified type                    |
+| `.optional()` | ❌ No      | Field can be omitted (not supported)                   |
+| `.nullish()`  | ❌ No      | Allows `null`, `undefined`, or omitted (not supported) |
+
+## Related Information
+
+- For more details on structured output generation, see [Generating Structured Data](/docs/ai-sdk-core/generating-structured-data)
+- For OpenAI-specific structured output configuration, see [OpenAI Provider - Structured Outputs](/providers/ai-sdk-providers/openai#structured-outputs)

package/docs/09-troubleshooting/30-model-is-not-assignable-to-type.mdx

@@ -0,0 +1,21 @@
+---
+title: Model is not assignable to type "LanguageModelV1"
+description: Troubleshooting errors related to incompatible models.
+---
+
+# Model is not assignable to type "LanguageModelV1"
+
+## Issue
+
+I have updated the AI SDK and now I get the following error: `Type 'SomeModel' is not assignable to type 'LanguageModelV1'.`
+
+<Note>Similar errors can occur with `EmbeddingModelV3` as well.</Note>
+
+## Background
+
+Sometimes new features are being added to the model specification.
+This can cause incompatibilities with older provider versions.
+
+## Solution
+
+Update your provider packages and the AI SDK to the latest version.

package/docs/09-troubleshooting/40-typescript-cannot-find-namespace-jsx.mdx

@@ -0,0 +1,24 @@
+---
+title: TypeScript error "Cannot find namespace 'JSX'"
+description: Troubleshooting errors related to TypeScript and JSX.
+---
+
+# TypeScript error "Cannot find namespace 'JSX'"
+
+## Issue
+
+I am using the AI SDK in a project without React, e.g. an Hono server, and I get the following error:
+`error TS2503: Cannot find namespace 'JSX'.`
+
+## Background
+
+The AI SDK has a dependency on `@types/react` which defines the `JSX` namespace.
+It will be removed in the next major version of the AI SDK.
+
+## Solution
+
+You can install the `@types/react` package as a dependency to fix the error.
+
+```bash
+npm install @types/react
+```

package/docs/09-troubleshooting/50-react-maximum-update-depth-exceeded.mdx

@@ -0,0 +1,39 @@
+---
+title: React error "Maximum update depth exceeded"
+description: Troubleshooting errors related to the "Maximum update depth exceeded" error.
+---
+
+# React error "Maximum update depth exceeded"
+
+## Issue
+
+I am using the AI SDK in a React project with the `useChat` or `useCompletion` hooks
+and I get the following error when AI responses stream in: `Maximum update depth exceeded`.
+
+## Background
+
+By default, the UI is re-rendered on every chunk that arrives.
+This can overload the rendering, especially on slower devices or when complex components
+need updating (e.g. Markdown). Throttling can mitigate this.
+
+## Solution
+
+Use the `experimental_throttle` option to throttle the UI updates:
+
+### `useChat`
+
+```tsx filename="page.tsx" highlight="2-3"
+const { messages, ... } = useChat({
+  // Throttle the messages and data updates to 50ms:
+  experimental_throttle: 50
+})
+```
+
+### `useCompletion`
+
+```tsx filename="page.tsx" highlight="2-3"
+const { completion, ... } = useCompletion({
+  // Throttle the completion and data updates to 50ms:
+  experimental_throttle: 50
+})
+```

package/docs/09-troubleshooting/60-jest-cannot-find-module-ai-rsc.mdx

@@ -0,0 +1,22 @@
+---
+title: "Jest: cannot find module '@ai-sdk/rsc'"
+description: "Troubleshooting AI SDK errors related to the Jest: cannot find module '@ai-sdk/rsc' error"
+---
+
+# Jest: cannot find module '@ai-sdk/rsc'
+
+## Issue
+
+I am using AI SDK RSC and am writing tests for my RSC components with Jest.
+
+I am getting the following error: `Cannot find module '@ai-sdk/rsc'`.
+
+## Solution
+
+Configure the module resolution via `jest config update` in `moduleNameMapper`:
+
+```json filename="jest.config.js"
+"moduleNameMapper": {
+  "^@ai-sdk/rsc$": "<rootDir>/node_modules/@ai-sdk/rsc/dist"
+}
+```

package/docs/09-troubleshooting/index.mdx

@@ -0,0 +1,11 @@
+---
+title: Troubleshooting
+description: Troubleshooting information for common issues encountered with the AI SDK.
+collapsed: true
+---
+
+# Troubleshooting
+
+This section is designed to help you quickly identify and resolve common issues encountered with the AI SDK, ensuring a smoother and more efficient development experience.
+
+<Support />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "6.0.31",
+  "version": "6.0.32",
   "description": "AI SDK by Vercel - The AI Toolkit for TypeScript and JavaScript",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -9,11 +9,15 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
     "CHANGELOG.md",
     "internal.d.ts",
     "README.md",
     "test.d.ts"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -37,8 +41,8 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
     "@ai-sdk/gateway": "3.0.13",
-    "@ai-sdk/provider-utils": "4.0.5",
-    "@ai-sdk/provider": "3.0.2"
+    "@ai-sdk/provider": "3.0.2",
+    "@ai-sdk/provider-utils": "4.0.5"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",
@@ -92,7 +96,7 @@
   "scripts": {
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch --tsconfig tsconfig.build.json",
-    "clean": "del-cli dist *.tsbuildinfo",
+    "clean": "del-cli dist docs *.tsbuildinfo",
     "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
     "prettier-check": "prettier --check \"./**/*.ts*\"",