@@ -0,0 +1,443 @@
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+```