@fairyhunter13/ai-sdk 6.0.116-fork.1

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,76 @@
+---
+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 structured output generation with OpenAI, 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 { generateText, Output } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+const result = await generateText({
+  model: openai('gpt-4o-2024-08-06'),
+  output: Output.object({
+    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 { generateText, Output } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { z } from 'zod';
+
+// Correct approach - use .nullable()
+const result = await generateText({
+  model: openai('gpt-4o-2024-08-06'),
+  output: Output.object({
+    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.output);
+// { 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/21-missing-tool-results-error.mdx

@@ -0,0 +1,82 @@
+---
+title: Missing Tool Results Error
+description: How to fix the "Tool results are missing for tool calls" error when using the AI SDK.
+---
+
+# Missing Tool Results Error
+
+## Issue
+
+You encounter the error `AI_MissingToolResultsError` with a message like:
+
+> Tool results are missing for tool calls: ...
+
+## Cause
+
+This error occurs when you attempt to send a new message to the Large Language Model (LLM) while there are pending tool calls from a previous turn that have not yet been resolved.
+
+The AI SDK core logic validates that all `tool-call` parts in the conversation history are resolved before proceeding. "Resolved" typically means:
+
+1. The tool has been executed and a `tool-result` has been added to the history.
+2. Or, the tool call has triggered a `tool-approval-response` (if using tool approvals).
+
+If a tool call is found without a corresponding result or approval response, this error is thrown to prevent sending an invalid conversation history to the model.
+
+## Solution
+
+Ensure that every tool call in your conversation history is properly handled.
+
+### 1. Provide Tool Results
+
+For standard tool calls, ensure that you provide the output of the tool execution.
+
+```typescript
+const messages = [
+  { role: 'user', content: 'What is the weather in NY?' },
+  {
+    role: 'assistant',
+    content: [
+      {
+        type: 'tool-call',
+        toolCallId: 'call_123',
+        toolName: 'getWeather',
+        args: { location: 'New York' },
+      },
+    ],
+  },
+  // You MUST include this tool message with the result:
+  {
+    role: 'tool',
+    content: [
+      {
+        type: 'tool-result',
+        toolCallId: 'call_123',
+        toolName: 'getWeather',
+        result: 'Sunny, 25°C',
+      },
+    ],
+  },
+  // Now you can add a new user message
+  { role: 'user', content: 'And in London?' },
+];
+```
+
+### 2. Handle Tool Approvals
+
+If you are using the tool approval workflow, ensure that you include the `tool-approval-response`.
+
+```typescript
+const messages = [
+  // ... assistant requests tool execution (needs approval)
+  {
+    role: 'tool',
+    content: [
+      {
+        type: 'tool-approval-response',
+        approvalId: 'approval_123',
+        approved: true, // or false
+      },
+    ],
+  },
+];
+```

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 `EmbeddingModelV4` 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"
+}
+```