@@ -1,443 +0,0 @@
1----
2-title: Common Errors
3-description: Reference for common AI SDK errors and how to resolve them.
4----
5-
6-# Common Errors
7-
8-## `maxTokens` → `maxOutputTokens`
9-
10-```typescript
11-// ❌ Incorrect
12-const result = await generateText({
13- model: "anthropic/claude-opus-4.5",
14- maxTokens: 512, // deprecated: use `maxOutputTokens` instead
15- prompt: "Write a short story",
16-});
17-
18-// ✅ Correct
19-const result = await generateText({
20- model: "anthropic/claude-opus-4.5",
21- maxOutputTokens: 512,
22- prompt: "Write a short story",
23-});
24-```
25-
26-## `maxSteps` → `stopWhen: stepCountIs(n)`
27-
28-```typescript
29-// ❌ Incorrect
30-const result = await generateText({
31- model: "anthropic/claude-opus-4.5",
32- tools: { weather },
33- maxSteps: 5, // deprecated: use `stopWhen: stepCountIs(n)` instead
34- prompt: "What is the weather in NYC?",
35-});
36-
37-// ✅ Correct
38-import { generateText, stepCountIs } from "ai";
39-
40-const result = await generateText({
41- model: "anthropic/claude-opus-4.5",
42- tools: { weather },
43- stopWhen: stepCountIs(5),
44- prompt: "What is the weather in NYC?",
45-});
46-```
47-
48-## `parameters` → `inputSchema` (in tool definition)
49-
50-```typescript
51-// ❌ Incorrect
52-const weatherTool = tool({
53- description: "Get weather for a location",
54- parameters: z.object({
55- // deprecated: use `inputSchema` instead
56- location: z.string(),
57- }),
58- execute: async ({ location }) => ({ location, temp: 72 }),
59-});
60-
61-// ✅ Correct
62-const weatherTool = tool({
63- description: "Get weather for a location",
64- inputSchema: z.object({
65- location: z.string(),
66- }),
67- execute: async ({ location }) => ({ location, temp: 72 }),
68-});
69-```
70-
71-## `generateObject` → `generateText` with `output`
72-
73-`generateObject` is deprecated. Use `generateText` with the `output` option instead.
74-
75-```typescript
76-// ❌ Deprecated
77-import { generateObject } from "ai"; // deprecated: use `generateText` with `output` instead
78-
79-const result = await generateObject({
80- // deprecated function
81- model: "anthropic/claude-opus-4.5",
82- schema: z.object({
83- // deprecated: use `Output.object({ schema })` instead
84- recipe: z.object({
85- name: z.string(),
86- ingredients: z.array(z.string()),
87- }),
88- }),
89- prompt: "Generate a recipe for chocolate cake",
90-});
91-
92-// ✅ Correct
93-import { generateText, Output } from "ai";
94-
95-const result = await generateText({
96- model: "anthropic/claude-opus-4.5",
97- output: Output.object({
98- schema: z.object({
99- recipe: z.object({
100- name: z.string(),
101- ingredients: z.array(z.string()),
102- }),
103- }),
104- }),
105- prompt: "Generate a recipe for chocolate cake",
106-});
107-
108-console.log(result.output); // typed object
109-```
110-
111-## Manual JSON parsing → `generateText` with `output`
112-
113-```typescript
114-// ❌ Incorrect
115-const result = await generateText({
116- model: "anthropic/claude-opus-4.5",
117- prompt: `Extract the user info as JSON: { "name": string, "age": number }
118-
119- Input: John is 25 years old`,
120-});
121-const parsed = JSON.parse(result.text);
122-
123-// ✅ Correct
124-import { generateText, Output } from "ai";
125-
126-const result = await generateText({
127- model: "anthropic/claude-opus-4.5",
128- output: Output.object({
129- schema: z.object({
130- name: z.string(),
131- age: z.number(),
132- }),
133- }),
134- prompt: "Extract the user info: John is 25 years old",
135-});
136-
137-console.log(result.output); // { name: 'John', age: 25 }
138-```
139-
140-## Other `output` options
141-
142-```typescript
143-// Output.array - for generating arrays of items
144-const result = await generateText({
145- model: "anthropic/claude-opus-4.5",
146- output: Output.array({
147- element: z.object({
148- city: z.string(),
149- country: z.string(),
150- }),
151- }),
152- prompt: "List 5 capital cities",
153-});
154-
155-// Output.choice - for selecting from predefined options
156-const result = await generateText({
157- model: "anthropic/claude-opus-4.5",
158- output: Output.choice({
159- options: ["positive", "negative", "neutral"] as const,
160- }),
161- prompt: "Classify the sentiment: I love this product!",
162-});
163-
164-// Output.json - for untyped JSON output
165-const result = await generateText({
166- model: "anthropic/claude-opus-4.5",
167- output: Output.json(),
168- prompt: "Return some JSON data",
169-});
170-```
171-
172-## `toDataStreamResponse` → `toUIMessageStreamResponse`
173-
174-When using `useChat` on the frontend, use `toUIMessageStreamResponse()` instead of `toDataStreamResponse()`. The UI message stream format is designed to work with the chat UI components and handles message state correctly.
175-
176-```typescript
177-// ❌ Incorrect (when using useChat)
178-const result = streamText({
179- // config
180-});
181-
182-return result.toDataStreamResponse(); // deprecated for useChat: use toUIMessageStreamResponse
183-
184-// ✅ Correct
185-const result = streamText({
186- // config
187-});
188-
189-return result.toUIMessageStreamResponse();
190-```
191-
192-## Removed managed input state in `useChat`
193-
194-The `useChat` hook no longer manages input state internally. You must now manage input state manually.
195-
196-```tsx
197-// ❌ Deprecated
198-import { useChat } from "@ai-sdk/react";
199-
200-export default function Page() {
201- const {
202- input, // deprecated: manage input state manually with useState
203- handleInputChange, // deprecated: use custom onChange handler
204- handleSubmit, // deprecated: use sendMessage() instead
205- } = useChat({
206- api: "/api/chat", // deprecated: use `transport: new DefaultChatTransport({ api })` instead
207- });
208-
209- return (
210- <form onSubmit={handleSubmit}>
211- <input value={input} onChange={handleInputChange} />
212- <button type="submit">Send</button>
213- </form>
214- );
215-}
216-
217-// ✅ Correct
218-import { useChat } from "@ai-sdk/react";
219-import { DefaultChatTransport } from "ai";
220-import { useState } from "react";
221-
222-export default function Page() {
223- const [input, setInput] = useState("");
224- const { sendMessage } = useChat({
225- transport: new DefaultChatTransport({ api: "/api/chat" }),
226- });
227-
228- const handleSubmit = (e) => {
229- e.preventDefault();
230- sendMessage({ text: input });
231- setInput("");
232- };
233-
234- return (
235- <form onSubmit={handleSubmit}>
236- <input value={input} onChange={(e) => setInput(e.target.value)} />
237- <button type="submit">Send</button>
238- </form>
239- );
240-}
241-```
242-
243-## `tool-invocation` → `tool-{toolName}` (typed tool parts)
244-
245-When rendering messages with `useChat`, use the typed tool part names (`tool-{toolName}`) instead of the generic `tool-invocation` type. This provides better type safety and access to tool-specific input/output types.
246-
247-> For end-to-end type-safety, see [Type-Safe Agents](type-safe-agents.md).
248-
249-Typed tool parts also use different property names:
250-
251-- `part.args` → `part.input`
252-- `part.result` → `part.output`
253-
254-```tsx
255-// ❌ Incorrect - using generic tool-invocation
256-{
257- message.parts.map((part, i) => {
258- switch (part.type) {
259- case "text":
260- return <div key={`${message.id}-${i}`}>{part.text}</div>;
261- case "tool-invocation": // deprecated: use typed tool parts instead
262- return (
263- <pre key={`${message.id}-${i}`}>
264- {JSON.stringify(part.toolInvocation, null, 2)}
265- </pre>
266- );
267- }
268- });
269-}
270-
271-// ✅ Correct - using typed tool parts (recommended)
272-{
273- message.parts.map((part) => {
274- switch (part.type) {
275- case "text":
276- return part.text;
277- case "tool-askForConfirmation":
278- // handle askForConfirmation tool
279- break;
280- case "tool-getWeatherInformation":
281- // handle getWeatherInformation tool
282- break;
283- }
284- });
285-}
286-
287-// ✅ Alternative - using isToolUIPart as a catch-all
288-import { isToolUIPart } from "ai";
289-
290-{
291- message.parts.map((part) => {
292- if (part.type === "text") {
293- return part.text;
294- }
295- if (isToolUIPart(part)) {
296- // handle any tool part generically
297- return (
298- <div key={part.toolCallId}>
299- {part.toolName}: {part.state}
300- </div>
301- );
302- }
303- });
304-}
305-```
306-
307-## `useChat` state-dependent property access
308-
309-Tool part properties are only available in certain states. TypeScript will error if you access them without checking state first.
310-
311-```tsx
312-// ❌ Incorrect - input may be undefined during streaming
313-// TS18048: 'part.input' is possibly 'undefined'
314-if (part.type === "tool-getWeather") {
315- const location = part.input.location;
316-}
317-
318-// ✅ Correct - check for input-available or output-available
319-if (
320- part.type === "tool-getWeather" &&
321- (part.state === "input-available" || part.state === "output-available")
322-) {
323- const location = part.input.location;
324-}
325-
326-// ❌ Incorrect - output is only available after execution
327-// TS18048: 'part.output' is possibly 'undefined'
328-if (part.type === "tool-getWeather") {
329- const weather = part.output;
330-}
331-
332-// ✅ Correct - check for output-available
333-if (part.type === "tool-getWeather" && part.state === "output-available") {
334- const location = part.input.location;
335- const weather = part.output;
336-}
337-```
338-
339-## `part.toolInvocation.args` → `part.input`
340-
341-```tsx
342-// ❌ Incorrect
343-if (part.type === "tool-invocation") {
344- // deprecated: use `part.input` on typed tool parts instead
345- const location = part.toolInvocation.args.location;
346-}
347-
348-// ✅ Correct
349-if (
350- part.type === "tool-getWeather" &&
351- (part.state === "input-available" || part.state === "output-available")
352-) {
353- const location = part.input.location;
354-}
355-```
356-
357-## `part.toolInvocation.result` → `part.output`
358-
359-```tsx
360-// ❌ Incorrect
361-if (part.type === "tool-invocation") {
362- // deprecated: use `part.output` on typed tool parts instead
363- const weather = part.toolInvocation.result;
364-}
365-
366-// ✅ Correct
367-if (part.type === "tool-getWeather" && part.state === "output-available") {
368- const weather = part.output;
369-}
370-```
371-
372-## `part.toolInvocation.toolCallId` → `part.toolCallId`
373-
374-```tsx
375-// ❌ Incorrect
376-if (part.type === "tool-invocation") {
377- // deprecated: use `part.toolCallId` on typed tool parts instead
378- const id = part.toolInvocation.toolCallId;
379-}
380-
381-// ✅ Correct
382-if (part.type === "tool-getWeather") {
383- const id = part.toolCallId;
384-}
385-```
386-
387-## Tool invocation states renamed
388-
389-```tsx
390-// ❌ Incorrect
391-switch (part.toolInvocation.state) {
392- case "partial-call": // deprecated: use `input-streaming` instead
393- return <div>Loading...</div>;
394- case "call": // deprecated: use `input-available` instead
395- return <div>Executing...</div>;
396- case "result": // deprecated: use `output-available` instead
397- return <div>Done</div>;
398-}
399-
400-// ✅ Correct
401-switch (part.state) {
402- case "input-streaming":
403- return <div>Loading...</div>;
404- case "input-available":
405- return <div>Executing...</div>;
406- case "output-available":
407- return <div>Done</div>;
408-}
409-```
410-
411-## `addToolResult` → `addToolOutput`
412-
413-```tsx
414-// ❌ Incorrect
415-addToolResult({
416- // deprecated: use `addToolOutput` instead
417- toolCallId: part.toolInvocation.toolCallId,
418- result: "Yes, confirmed.", // deprecated: use `output` instead
419-});
420-
421-// ✅ Correct
422-addToolOutput({
423- tool: "askForConfirmation",
424- toolCallId: part.toolCallId,
425- output: "Yes, confirmed.",
426-});
427-```
428-
429-## `messages` → `uiMessages` in `createAgentUIStreamResponse`
430-
431-```typescript
432-// ❌ Incorrect
433-return createAgentUIStreamResponse({
434- agent: myAgent,
435- messages, // incorrect: use `uiMessages` instead
436-});
437-
438-// ✅ Correct
439-return createAgentUIStreamResponse({
440- agent: myAgent,
441- uiMessages: messages,
442-});
443-```