{messages.map(message => {
const { metadata } = message;
return (
);
}
```
### UI Message Stream
The UI Message Stream enables streaming any content parts from the server to the client. With this stream, you can send structured data like custom sources from your RAG pipeline directly to your UI. The stream writer is simply a utility that makes it easy to write to this message stream.
```ts
const stream = createUIMessageStream({
execute: writer => {
// stream custom sources
writer.write({
type: 'source',
value: {
type: 'source',
sourceType: 'url',
id: 'source-1',
url: 'https://example.com',
title: 'Example Source',
},
});
},
});
```
On the client, these will be added to the ordered `message.parts` array.
### Data Parts
The new stream writer also enables a type-safe way to stream arbitrary data from the server to the client and display it in your UI.
You can create and stream custom data parts on the server:
```tsx
// On the server
const stream = createUIMessageStream({
execute: writer => {
// Initial update
writer.write({
type: 'data-weather', // Custom type
id: toolCallId, // ID for updates
data: { city, status: 'loading' }, // Your data
});
// Later, update the same part
writer.write({
type: 'data-weather',
id: toolCallId,
data: { city, weather, status: 'success' },
});
},
});
```
On the client, you can render these parts with full type safety:
```tsx
{
message.parts
.filter(part => part.type === 'data-weather') // type-safe
.map((part, index) => (
{metadata?.duration &&
);
})}
Duration: {metadata.duration}ms
}
{metadata?.model && Model: {metadata.model}
}
{metadata?.totalTokens && (
Total tokens: {metadata.totalTokens}
)}
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.content}
))}
);
}
```
```ts filename='app/api/chat/route.ts'
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
// Allow streaming responses up to 30 seconds
export const maxDuration = 30;
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4-turbo'),
system: 'You are a helpful assistant.',
messages,
});
return result.toDataStreamResponse();
}
```
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.content}
))}
{(status === 'submitted' || status === 'streaming') && (
{status === 'submitted' &&
)}
);
}
```
### Error State
Similarly, the `error` state reflects the error object thrown during the fetch request.
It can be used to display an error message, disable the submit button, or show a retry button:
{messages.map(m => (
);
}
```
Please also see the [error handling](/docs/ai-sdk-ui/error-handling) guide for more information.
### Modify messages
Sometimes, you may want to directly modify some existing messages. For example, a delete button can be added to each message to allow users to remove them from the chat history.
The `setMessages` function can help you achieve these tasks:
```tsx
const { messages, setMessages, ... } = useChat()
const handleDelete = (id) => {
setMessages(messages.filter(message => message.id !== id))
}
return <>
{messages.map(message => (
{m.role}: {m.content}
))}
{error && (
<>
An error occurred.
)}
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.content}
))}
...
```
You can think of `messages` and `setMessages` as a pair of `state` and `setState` in React.
### Controlled input
In the initial example, we have `handleSubmit` and `handleInputChange` callbacks that manage the input changes and form submissions. These are handy for common use cases, but you can also use uncontrolled APIs for more advanced scenarios such as form validation or customized components.
The following example demonstrates how to use more granular APIs like `setInput` and `append` with your custom input and submit button components:
```tsx
const { input, setInput, append } = useChat()
return <>
{messages.map(m => (
);
}
```
You can retrieve these custom fields on your server side by destructuring the request body:
```ts filename="app/api/chat/route.ts" highlight="3"
export async function POST(req: Request) {
// Extract addition information ("customKey") from the body of the request:
const { messages, customKey } = await req.json();
//...
}
```
## Controlling the response stream
With `streamText`, you can control how error messages and usage information are sent back to the client.
### Error Messages
By default, the error message is masked for security reasons.
The default error message is "An error occurred."
You can forward error messages or send your own error message by providing a `getErrorMessage` function:
```ts filename="app/api/chat/route.ts" highlight="13-27"
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4o'),
messages,
});
return result.toDataStreamResponse({
getErrorMessage: error => {
if (error == null) {
return 'unknown error';
}
if (typeof error === 'string') {
return error;
}
if (error instanceof Error) {
return error.message;
}
return JSON.stringify(error);
},
});
}
```
### Usage Information
By default, the usage information is sent back to the client. You can disable it by setting the `sendUsage` option to `false`:
```ts filename="app/api/chat/route.ts" highlight="13"
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: openai('gpt-4o'),
messages,
});
return result.toDataStreamResponse({
sendUsage: false,
});
}
```
### Text Streams
`useChat` can handle plain text streams by setting the `streamProtocol` option to `text`:
```tsx filename="app/page.tsx" highlight="7"
'use client';
import { useChat } from '@ai-sdk/react';
export default function Chat() {
const { messages } = useChat({
streamProtocol: 'text',
});
return <>...;
}
```
This configuration also works with other backend servers that stream plain text.
Check out the [stream protocol guide](/docs/ai-sdk-ui/stream-protocol) for more information.
{m.role}: {m.content}
))}
{messages.map(m => (
);
}
```
## Reasoning
Some models such as as DeepSeek `deepseek-reasoner`
and Anthropic `claude-3-7-sonnet-20250219` support reasoning tokens.
These tokens are typically sent before the message content.
You can forward them to the client with the `sendReasoning` option:
```ts filename="app/api/chat/route.ts" highlight="13"
import { deepseek } from '@ai-sdk/deepseek';
import { streamText } from 'ai';
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: deepseek('deepseek-reasoner'),
messages,
});
return result.toDataStreamResponse({
sendReasoning: true,
});
}
```
On the client side, you can access the reasoning parts of the message object.
They have a `details` property that contains the reasoning and redacted reasoning parts.
You can also use `reasoning` to access just the reasoning as a string.
```tsx filename="app/page.tsx"
messages.map(message => (
{m.role}: {m.content}
))}
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.parts.map((part, index) => {
// text parts:
if (part.type === 'text') {
return
));
```
## Sources
Some providers such as [Perplexity](/providers/ai-sdk-providers/perplexity#sources) and
[Google Generative AI](/providers/ai-sdk-providers/google-generative-ai#sources) include sources in the response.
Currently sources are limited to web pages that ground the response.
You can forward them to the client with the `sendSources` option:
```ts filename="app/api/chat/route.ts" highlight="13"
import { perplexity } from '@ai-sdk/perplexity';
import { streamText } from 'ai';
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: perplexity('sonar-pro'),
messages,
});
return result.toDataStreamResponse({
sendSources: true,
});
}
```
On the client side, you can access source parts of the message object.
Here is an example that renders the sources as links at the bottom of the message:
```tsx filename="app/page.tsx"
messages.map(message => (
{part.text}
;
}
// reasoning parts:
if (part.type === 'reasoning') {
return (
{part.details.map(detail =>
detail.type === 'text' ? detail.text : '',
)}
);
}
})}
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.parts
.filter(part => part.type !== 'source')
.map((part, index) => {
if (part.type === 'text') {
return
));
```
## Image Generation
Some models such as Google `gemini-2.0-flash-exp` support image generation.
When images are generated, they are exposed as files to the client.
On the client side, you can access file parts of the message object
and render them as images.
```tsx filename="app/page.tsx"
messages.map(message => (
{part.text}
;
}
})}
{message.parts
.filter(part => part.type === 'source')
.map(part => (
[
{part.source.title ?? new URL(part.source.url).hostname}
]
))}
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.parts.map((part, index) => {
if (part.type === 'text') {
return 
);
}
})}
));
```
## Attachments (Experimental)
The `useChat` hook supports sending attachments along with a message as well as rendering them on the client. This can be useful for building applications that involve sending images, files, or other media content to the AI provider.
There are two ways to send attachments with a message, either by providing a `FileList` object or a list of URLs to the `handleSubmit` function:
### FileList
By using `FileList`, you can send multiple files as attachments along with a message using the file input element. The `useChat` hook will automatically convert them into data URLs and send them to the AI provider.
{part.text}
;
} else if (part.type === 'file' && part.mimeType.startsWith('image/')) {
return (
{messages.map(message => (
))}
{`${message.role}: `}
{message.content}
{message.experimental_attachments
?.filter(attachment =>
attachment.contentType.startsWith('image/'),
)
.map((attachment, index) => (
))}
{messages.map(message => (
))}
{`${message.role}: `}
{message.content}
{message.experimental_attachments
?.filter(attachment =>
attachment.contentType?.startsWith('image/'),
)
.map((attachment, index) => (
))}
{messages.map(m => (
);
}
```
## Storing messages
`useChat` sends the chat id and the messages to the backend.
We have enabled the `sendExtraMessageFields` option to send the id and createdAt fields,
meaning that we store messages in the `useChat` message format.
{m.role === 'user' ? 'User: ' : 'AI: '}
{m.content}
))}
{`${message.role}: `}
{message.parts.map(part => {
switch (part.type) {
// render text parts as simple text:
case 'text':
return part.text;
// for tool invocations, distinguish between the tools and the state:
case 'tool-invocation': {
const callId = part.toolInvocation.toolCallId;
switch (part.toolInvocation.toolName) {
case 'askForConfirmation': {
switch (part.toolInvocation.state) {
case 'call':
return (
))}
);
}
```
## Tool call streaming
You can stream tool calls while they are being generated by enabling the
`toolCallStreaming` option in `streamText`.
```tsx filename='app/api/chat/route.ts' highlight="5"
export async function POST(req: Request) {
// ...
const result = streamText({
toolCallStreaming: true,
// ...
});
return result.toDataStreamResponse();
}
```
When the flag is enabled, partial tool calls will be streamed as part of the data stream.
They are available through the `useChat` hook.
The tool invocation parts of assistant messages will also contain partial tool calls.
You can use the `state` property of the tool invocation to render the correct UI.
```tsx filename='app/page.tsx' highlight="9,10"
export default function Chat() {
// ...
return (
<>
{messages?.map(message => (
{part.toolInvocation.args.message}
);
case 'result':
return (
Location access allowed:{' '}
{part.toolInvocation.result}
);
}
break;
}
case 'getLocation': {
switch (part.toolInvocation.state) {
case 'call':
return Getting location...
;
case 'result':
return (
Location: {part.toolInvocation.result}
);
}
break;
}
case 'getWeatherInformation': {
switch (part.toolInvocation.state) {
// example of pre-rendering streaming tool calls:
case 'partial-call':
return (
{JSON.stringify(part.toolInvocation, null, 2)}
);
case 'call':
return (
Getting weather information for{' '}
{part.toolInvocation.args.city}...
);
case 'result':
return (
Weather in {part.toolInvocation.args.city}:{' '}
{part.toolInvocation.result}
);
}
break;
}
}
}
}
})}
{message.parts.map(part => {
if (part.type === 'tool-invocation') {
switch (part.toolInvocation.state) {
case 'partial-call':
return <>render partial tool call;
case 'call':
return <>render full tool call;
case 'result':
return <>render tool result;
}
}
})}
))}
);
}
```
## Step start parts
When you are using multi-step tool calls, the AI SDK will add step start parts to the assistant messages.
If you want to display boundaries between tool invocations, you can use the `step-start` parts as follows:
```tsx filename='app/page.tsx'
// ...
// where you render the message parts:
message.parts.map((part, index) => {
switch (part.type) {
case 'step-start':
// show step boundaries as horizontal lines:
return index > 0 ? (
{messages.map(message => (
))}
);
}
```
To handle the chat requests and model responses, set up an API route:
```ts filename="app/api/chat/route.ts"
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
export async function POST(request: Request) {
const { messages } = await request.json();
const result = streamText({
model: openai('gpt-4o'),
system: 'You are a friendly assistant!',
messages,
maxSteps: 5,
});
return result.toDataStreamResponse();
}
```
This API route uses the `streamText` function to process chat messages and stream the model's responses back to the client.
### Create a Tool
Before enhancing your chat interface with dynamic UI elements, you need to create a tool and corresponding React component. A tool will allow the model to perform a specific action, such as fetching weather information.
Create a new file called `ai/tools.ts` with the following content:
```ts filename="ai/tools.ts"
import { tool as createTool } from 'ai';
import { z } from 'zod';
export const weatherTool = createTool({
description: 'Display the weather for a location',
parameters: z.object({
location: z.string().describe('The location to get the weather for'),
}),
execute: async function ({ location }) {
await new Promise(resolve => setTimeout(resolve, 2000));
return { weather: 'Sunny', temperature: 75, location };
},
});
export const tools = {
displayWeather: weatherTool,
};
```
In this file, you've created a tool called `weatherTool`. This tool simulates fetching weather information for a given location. This tool will return simulated data after a 2-second delay. In a real-world application, you would replace this simulation with an actual API call to a weather service.
### Update the API Route
Update the API route to include the tool you've defined:
```ts filename="app/api/chat/route.ts" highlight="3,13"
import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';
import { tools } from '@/ai/tools';
export async function POST(request: Request) {
const { messages } = await request.json();
const result = streamText({
model: openai('gpt-4o'),
system: 'You are a friendly assistant!',
messages,
maxSteps: 5,
tools,
});
return result.toDataStreamResponse();
}
```
Now that you've defined the tool and added it to your `streamText` call, let's build a React component to display the weather information it returns.
### Create UI Components
Create a new file called `components/weather.tsx`:
```tsx filename="components/weather.tsx"
type WeatherProps = {
temperature: number;
weather: string;
location: string;
};
export const Weather = ({ temperature, weather, location }: WeatherProps) => {
return (
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.content}
Current Weather for {location}
Condition: {weather}
Temperature: {temperature}°C
{messages.map(message => (
))}
);
}
```
In this updated code snippet, you:
1. Check if the message has `toolInvocations`.
2. Check if the tool invocation state is 'result'.
3. If it's a result and the tool name is 'displayWeather', render the Weather component.
4. If the tool invocation state is not 'result', show a loading message.
This approach allows you to dynamically render UI components based on the model's responses, creating a more interactive and context-aware chat experience.
## Expanding Your Generative UI Application
You can enhance your chat application by adding more tools and components, creating a richer and more versatile user experience. Here's how you can expand your application:
### Adding More Tools
To add more tools, simply define them in your `ai/tools.ts` file:
```ts
// Add a new stock tool
export const stockTool = createTool({
description: 'Get price for a stock',
parameters: z.object({
symbol: z.string().describe('The stock symbol to get the price for'),
}),
execute: async function ({ symbol }) {
// Simulated API call
await new Promise(resolve => setTimeout(resolve, 2000));
return { symbol, price: 100 };
},
});
// Update the tools object
export const tools = {
displayWeather: weatherTool,
getStockPrice: stockTool,
};
```
Now, create a new file called `components/stock.tsx`:
```tsx
type StockProps = {
price: number;
symbol: string;
};
export const Stock = ({ price, symbol }: StockProps) => {
return (
{message.role === 'user' ? 'User: ' : 'AI: '}
{message.content}
{message.toolInvocations?.map(toolInvocation => {
const { toolName, toolCallId, state } = toolInvocation;
if (state === 'result') {
if (toolName === 'displayWeather') {
const { result } = toolInvocation;
return (
{toolName === 'displayWeather' ? (
);
}
})}
Loading weather...
) : null}
Stock Information
Symbol: {symbol}
Price: ${price}
{messages.map(message => (
))}
);
}
```
By following this pattern, you can continue to add more tools and components, expanding the capabilities of your Generative UI application.
---
title: Completion
description: Learn how to use the useCompletion hook.
---
# Completion
The `useCompletion` hook allows you to create a user interface to handle text completions in your application. It enables the streaming of text completions from your AI provider, manages the state for chat input, and updates the UI automatically as new messages are received.
In this guide, you will learn how to use the `useCompletion` hook in your application to generate text completions and stream them in real-time to your users.
## Example
```tsx filename='app/page.tsx'
'use client';
import { useCompletion } from '@ai-sdk/react';
export default function Page() {
const { completion, input, handleInputChange, handleSubmit } = useCompletion({
api: '/api/completion',
});
return (
);
}
```
```ts filename='app/api/completion/route.ts'
import { streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
// Allow streaming responses up to 30 seconds
export const maxDuration = 30;
export async function POST(req: Request) {
const { prompt }: { prompt: string } = await req.json();
const result = streamText({
model: openai('gpt-3.5-turbo'),
prompt,
});
return result.toDataStreamResponse();
}
```
In the `Page` component, the `useCompletion` hook will request to your AI provider endpoint whenever the user submits a message. The completion is then streamed back in real-time and displayed in the UI.
This enables a seamless text completion experience where the user can see the AI response as soon as it is available, without having to wait for the entire response to be received.
## Customized UI
`useCompletion` also provides ways to manage the prompt via code, show loading and error states, and update messages without being triggered by user interactions.
### Loading and error states
To show a loading spinner while the chatbot is processing the user's message, you can use the `isLoading` state returned by the `useCompletion` hook:
```tsx
const { isLoading, ... } = useCompletion()
return(
<>
{isLoading ? {message.role}
{message.content}
{message.toolInvocations?.map(toolInvocation => {
const { toolName, toolCallId, state } = toolInvocation;
if (state === 'result') {
if (toolName === 'displayWeather') {
const { result } = toolInvocation;
return (
{toolName === 'displayWeather' ? (
);
}
})}
Loading weather...
) : toolName === 'getStockPrice' ? (
Loading stock price...
) : (
Loading...
)}
{error.message}
: null}
)
```
### Controlled input
In the initial example, we have `handleSubmit` and `handleInputChange` callbacks that manage the input changes and form submissions. These are handy for common use cases, but you can also use uncontrolled APIs for more advanced scenarios such as form validation or customized components.
The following example demonstrates how to use more granular APIs like `setInput` with your custom input and submit button components:
```tsx
const { input, setInput } = useCompletion();
return (
<>
{notification?.name}
{notification?.message}
{notification?.name}
{notification?.message}
{notification?.name}
{notification?.message}
An error occurred.
}
{object?.notifications?.map((notification, index) => (
{notification?.name}
{notification?.message}
{object?.notifications?.map((notification, index) => (
))}
);
}
```
## Configure Request Options
You can configure the API endpoint, optional headers and credentials using the `api`, `headers` and `credentials` settings.
```tsx highlight="2-5"
const { submit, object } = useObject({
api: '/api/use-object',
headers: {
'X-Custom-Header': 'CustomValue',
},
credentials: 'include',
schema: yourSchema,
});
```
---
title: OpenAI Assistants
description: Learn how to use the useAssistant hook.
---
# OpenAI Assistants
The `useAssistant` hook allows you to handle the client state when interacting with an OpenAI compatible assistant API.
This hook is useful when you want to integrate assistant capabilities into your application,
with the UI updated automatically as the assistant is streaming its execution.
The `useAssistant` hook is supported in `@ai-sdk/react`, `ai/svelte`, and `ai/vue`.
## Example
```tsx filename='app/page.tsx'
'use client';
import { Message, useAssistant } from '@ai-sdk/react';
export default function Chat() {
const { status, messages, input, submitMessage, handleInputChange } =
useAssistant({ api: '/api/assistant' });
return (
{notification?.name}
{notification?.message}
{messages.map((m: Message) => (
);
}
```
```tsx filename='app/api/assistant/route.ts'
import { AssistantResponse } from 'ai';
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: process.env.OPENAI_API_KEY || '',
});
// Allow streaming responses up to 30 seconds
export const maxDuration = 30;
export async function POST(req: Request) {
// Parse the request body
const input: {
threadId: string | null;
message: string;
} = await req.json();
// Create a thread if needed
const threadId = input.threadId ?? (await openai.beta.threads.create({})).id;
// Add a message to the thread
const createdMessage = await openai.beta.threads.messages.create(threadId, {
role: 'user',
content: input.message,
});
return AssistantResponse(
{ threadId, messageId: createdMessage.id },
async ({ forwardStream, sendDataMessage }) => {
// Run the assistant on the thread
const runStream = openai.beta.threads.runs.stream(threadId, {
assistant_id:
process.env.ASSISTANT_ID ??
(() => {
throw new Error('ASSISTANT_ID is not set');
})(),
});
// forward run status would stream message deltas
let runResult = await forwardStream(runStream);
// status can be: queued, in_progress, requires_action, cancelling, cancelled, failed, completed, or expired
while (
runResult?.status === 'requires_action' &&
runResult.required_action?.type === 'submit_tool_outputs'
) {
const tool_outputs =
runResult.required_action.submit_tool_outputs.tool_calls.map(
(toolCall: any) => {
const parameters = JSON.parse(toolCall.function.arguments);
switch (toolCall.function.name) {
// configure your tool calls here
default:
throw new Error(
`Unknown tool call function: ${toolCall.function.name}`,
);
}
},
);
runResult = await forwardStream(
openai.beta.threads.runs.submitToolOutputsStream(
threadId,
runResult.id,
{ tool_outputs },
),
);
}
},
);
}
```
## Customized UI
`useAssistant` also provides ways to manage the chat message and input states via code and show loading and error states.
### Loading and error states
To show a loading spinner while the assistant is running the thread, you can use the `status` state returned by the `useAssistant` hook:
```tsx
const { status, ... } = useAssistant()
return(
<>
{status === "in_progress" ?
{`${m.role}: `}
{m.role !== 'data' && m.content}
{m.role === 'data' && (
<>
{(m.data as any).description}
))}
{status === 'in_progress' && }
{JSON.stringify(m.data, null, 2)}
)}
{error.message}
: null}
)
```
### Controlled input
In the initial example, we have `handleSubmit` and `handleInputChange` callbacks that manage the input changes and form submissions. These are handy for common use cases, but you can also use uncontrolled APIs for more advanced scenarios such as form validation or customized components.
The following example demonstrates how to use more granular APIs like `append` with your custom input and submit button components:
```tsx
const { append } = useAssistant();
return (
<>
{m.annotations && <>{JSON.stringify(m.annotations)}}
))}
);
```
### Updating and Clearing Data
You can update and clear the `data` object of the `useChat` hook using the `setData` function.
```tsx filename="page.tsx"
const { setData } = useChat();
// clear existing data
setData(undefined);
// set new data
setData([{ test: 'value' }]);
// transform existing data, e.g. adding additional values:
setData(currentData => [...currentData, { test: 'value' }]);
```
#### Example: Clear on Submit
```tsx filename="page.tsx" highlight="18-21"
'use client';
import { Message, useChat } from '@ai-sdk/react';
export default function Chat() {
const { messages, input, handleInputChange, handleSubmit, data, setData } =
useChat();
return (
<>
{data && {JSON.stringify(data, null, 2)}}
{messages?.map((m: Message) => (
{`${m.role}: ${m.content}`}
))}
);
}
```
---
title: Error Handling
description: Learn how to handle errors in the AI SDK UI
---
# Error Handling
### Error Helper Object
Each AI SDK UI hook also returns an [error](/docs/reference/ai-sdk-ui/use-chat#error) object that you can use to render the error in your UI.
You can use the error object to show an error message, disable the submit button, or show a retry button.
{messages.map(m => (
);
}
```
#### Alternative: replace last message
Alternatively you can write a custom submit handler that replaces the last message when an error is present.
```tsx file="app/page.tsx" highlight="15-21,33"
'use client';
import { useChat } from '@ai-sdk/react';
export default function Chat() {
const {
handleInputChange,
handleSubmit,
error,
input,
messages,
setMessages,
} = useChat({});
function customSubmit(event: React.FormEvent
{m.role}: {m.content}
))}
{error && (
<>
An error occurred.
)}
{messages.map(m => (
);
}
```
### Error Handling Callback
Errors can be processed by passing an [`onError`](/docs/reference/ai-sdk-ui/use-chat#on-error) callback function as an option to the [`useChat`](/docs/reference/ai-sdk-ui/use-chat), [`useCompletion`](/docs/reference/ai-sdk-ui/use-completion) or [`useAssistant`](/docs/reference/ai-sdk-ui/use-assistant) hooks.
The callback function receives an error object as an argument.
```tsx file="app/page.tsx" highlight="8-11"
import { useChat } from '@ai-sdk/react';
export default function Page() {
const {
/* ... */
} = useChat({
// handle error:
onError: error => {
console.error(error);
},
});
}
```
### Injecting Errors for Testing
You might want to create errors for testing.
You can easily do so by throwing an error in your route handler:
```ts file="app/api/chat/route.ts"
export async function POST(req: Request) {
throw new Error('This is a test error');
}
```
---
title: Smooth streaming japanese text
description: Learn how to stream smooth stream japanese text
---
# Smooth streaming japanese text
You can smooth stream japanese text by using the `smoothStream` function, and the following regex that splits either on words of japanese characters:
```tsx filename="page.tsx"
import { smoothStream } from 'ai';
import { useChat } from '@ai-sdk/react';
const { data } = useChat({
experimental_transform: smoothStream({
chunking: /[\u3040-\u309F\u30A0-\u30FF]|\S+\s+/,
}),
});
```
---
title: Smooth streaming chinese text
description: Learn how to stream smooth stream chinese text
---
# Smooth streaming chinese text
You can smooth stream chinese text by using the `smoothStream` function, and the following regex that splits either on words of chinese characters:
```tsx filename="page.tsx"
import { smoothStream } from 'ai';
import { useChat } from '@ai-sdk/react';
const { data } = useChat({
experimental_transform: smoothStream({
chunking: /[\u4E00-\u9FFF]|\S+\s+/,
}),
});
```
---
title: AI_APICallError
description: Learn how to fix AI_APICallError
---
# AI_APICallError
This error occurs when an API call fails.
## Properties
- `url`: The URL of the API request that failed
- `requestBodyValues`: The request body values sent to the API
- `statusCode`: The HTTP status code returned by the API
- `responseHeaders`: The response headers returned by the API
- `responseBody`: The response body returned by the API
- `isRetryable`: Whether the request can be retried based on the status code
- `data`: Any additional data associated with the error
## Checking for this Error
You can check if an error is an instance of `AI_APICallError` using:
```typescript
import { APICallError } from 'ai';
if (APICallError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_DownloadError
description: Learn how to fix AI_DownloadError
---
# AI_DownloadError
This error occurs when a download fails.
## Properties
- `url`: The URL that failed to download
- `statusCode`: The HTTP status code returned by the server
- `statusText`: The HTTP status text returned by the server
- `message`: The error message containing details about the download failure
## Checking for this Error
You can check if an error is an instance of `AI_DownloadError` using:
```typescript
import { DownloadError } from 'ai';
if (DownloadError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_EmptyResponseBodyError
description: Learn how to fix AI_EmptyResponseBodyError
---
# AI_EmptyResponseBodyError
This error occurs when the server returns an empty response body.
## Properties
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_EmptyResponseBodyError` using:
```typescript
import { EmptyResponseBodyError } from 'ai';
if (EmptyResponseBodyError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_InvalidArgumentError
description: Learn how to fix AI_InvalidArgumentError
---
# AI_InvalidArgumentError
This error occurs when an invalid argument was provided.
## Properties
- `parameter`: The name of the parameter that is invalid
- `value`: The invalid value
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_InvalidArgumentError` using:
```typescript
import { InvalidArgumentError } from 'ai';
if (InvalidArgumentError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_InvalidDataContentError
description: How to fix AI_InvalidDataContentError
---
# AI_InvalidDataContentError
This error occurs when the data content provided in a multi-modal message part is invalid. Check out the [ prompt examples for multi-modal messages ](/docs/foundations/prompts#message-prompts).
## Properties
- `content`: The invalid content value
- `message`: The error message describing the expected and received content types
## Checking for this Error
You can check if an error is an instance of `AI_InvalidDataContentError` using:
```typescript
import { InvalidDataContentError } from 'ai';
if (InvalidDataContentError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_InvalidDataContent
description: Learn how to fix AI_InvalidDataContent
---
# AI_InvalidDataContent
This error occurs when invalid data content is provided.
## Properties
- `content`: The invalid content value
- `message`: The error message
- `cause`: The cause of the error
## Checking for this Error
You can check if an error is an instance of `AI_InvalidDataContent` using:
```typescript
import { InvalidDataContent } from 'ai';
if (InvalidDataContent.isInstance(error)) {
// Handle the error
}
```
---
title: AI_InvalidMessageRoleError
description: Learn how to fix AI_InvalidMessageRoleError
---
# AI_InvalidMessageRoleError
This error occurs when an invalid message role is provided.
## Properties
- `role`: The invalid role value
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_InvalidMessageRoleError` using:
```typescript
import { InvalidMessageRoleError } from 'ai';
if (InvalidMessageRoleError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_InvalidPromptError
description: Learn how to fix AI_InvalidPromptError
---
# AI_InvalidPromptError
This error occurs when the prompt provided is invalid.
## Properties
- `prompt`: The invalid prompt value
- `message`: The error message
- `cause`: The cause of the error
## Checking for this Error
You can check if an error is an instance of `AI_InvalidPromptError` using:
```typescript
import { InvalidPromptError } from 'ai';
if (InvalidPromptError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_InvalidResponseDataError
description: Learn how to fix AI_InvalidResponseDataError
---
# AI_InvalidResponseDataError
This error occurs when the server returns a response with invalid data content.
## Properties
- `data`: The invalid response data value
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_InvalidResponseDataError` using:
```typescript
import { InvalidResponseDataError } from 'ai';
if (InvalidResponseDataError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_InvalidToolArgumentsError
description: Learn how to fix AI_InvalidToolArgumentsError
---
# AI_InvalidToolArgumentsError
This error occurs when invalid tool argument was provided.
## Properties
- `toolName`: The name of the tool with invalid arguments
- `toolArgs`: The invalid tool arguments
- `message`: The error message
- `cause`: The cause of the error
## Checking for this Error
You can check if an error is an instance of `AI_InvalidToolArgumentsError` using:
```typescript
import { InvalidToolArgumentsError } from 'ai';
if (InvalidToolArgumentsError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_JSONParseError
description: Learn how to fix AI_JSONParseError
---
# AI_JSONParseError
This error occurs when JSON fails to parse.
## Properties
- `text`: The text value that could not be parsed
- `message`: The error message including parse error details
## Checking for this Error
You can check if an error is an instance of `AI_JSONParseError` using:
```typescript
import { JSONParseError } from 'ai';
if (JSONParseError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_LoadAPIKeyError
description: Learn how to fix AI_LoadAPIKeyError
---
# AI_LoadAPIKeyError
This error occurs when API key is not loaded successfully.
## Properties
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_LoadAPIKeyError` using:
```typescript
import { LoadAPIKeyError } from 'ai';
if (LoadAPIKeyError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_LoadSettingError
description: Learn how to fix AI_LoadSettingError
---
# AI_LoadSettingError
This error occurs when a setting is not loaded successfully.
## Properties
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_LoadSettingError` using:
```typescript
import { LoadSettingError } from 'ai';
if (LoadSettingError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_MessageConversionError
description: Learn how to fix AI_MessageConversionError
---
# AI_MessageConversionError
This error occurs when message conversion fails.
## Properties
- `originalMessage`: The original message that failed conversion
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_MessageConversionError` using:
```typescript
import { MessageConversionError } from 'ai';
if (MessageConversionError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_NoAudioGeneratedError
description: Learn how to fix AI_NoAudioGeneratedError
---
# AI_NoAudioGeneratedError
This error occurs when no audio could be generated from the input.
## Properties
- `responses`: Array of responses
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_NoAudioGeneratedError` using:
```typescript
import { NoAudioGeneratedError } from 'ai';
if (NoAudioGeneratedError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_NoContentGeneratedError
description: Learn how to fix AI_NoContentGeneratedError
---
# AI_NoContentGeneratedError
This error occurs when the AI provider fails to generate content.
## Properties
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_NoContentGeneratedError` using:
```typescript
import { NoContentGeneratedError } from 'ai';
if (NoContentGeneratedError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_NoImageGeneratedError
description: Learn how to fix AI_NoImageGeneratedError
---
# AI_NoImageGeneratedError
This error occurs when the AI provider fails to generate an image.
It can arise due to the following reasons:
- The model failed to generate a response.
- The model generated an invalid response.
## Properties
- `message`: The error message.
- `responses`: Metadata about the image model responses, including timestamp, model, and headers.
- `cause`: The cause of the error. You can use this for more detailed error handling.
## Checking for this Error
You can check if an error is an instance of `AI_NoImageGeneratedError` using:
```typescript
import { generateImage, NoImageGeneratedError } from 'ai';
try {
await generateImage({ model, prompt });
} catch (error) {
if (NoImageGeneratedError.isInstance(error)) {
console.log('NoImageGeneratedError');
console.log('Cause:', error.cause);
console.log('Responses:', error.responses);
}
}
```
---
title: AI_NoObjectGeneratedError
description: Learn how to fix AI_NoObjectGeneratedError
---
# AI_NoObjectGeneratedError
This error occurs when the AI provider fails to generate a parsable object that conforms to the schema.
It can arise due to the following reasons:
- The model failed to generate a response.
- The model generated a response that could not be parsed.
- The model generated a response that could not be validated against the schema.
## Properties
- `message`: The error message.
- `text`: The text that was generated by the model. This can be the raw text or the tool call text, depending on the object generation mode.
- `response`: Metadata about the language model response, including response id, timestamp, and model.
- `usage`: Request token usage.
- `finishReason`: Request finish reason. For example 'length' if model generated maximum number of tokens, this could result in a JSON parsing error.
- `cause`: The cause of the error (e.g. a JSON parsing error). You can use this for more detailed error handling.
## Checking for this Error
You can check if an error is an instance of `AI_NoObjectGeneratedError` using:
```typescript
import { generateObject, NoObjectGeneratedError } from 'ai';
try {
await generateObject({ model, schema, prompt });
} catch (error) {
if (NoObjectGeneratedError.isInstance(error)) {
console.log('NoObjectGeneratedError');
console.log('Cause:', error.cause);
console.log('Text:', error.text);
console.log('Response:', error.response);
console.log('Usage:', error.usage);
console.log('Finish Reason:', error.finishReason);
}
}
```
---
title: AI_NoOutputSpecifiedError
description: Learn how to fix AI_NoOutputSpecifiedError
---
# AI_NoOutputSpecifiedError
This error occurs when no output format was specified for the AI response, and output-related methods are called.
## Properties
- `message`: The error message (defaults to 'No output specified.')
## Checking for this Error
You can check if an error is an instance of `AI_NoOutputSpecifiedError` using:
```typescript
import { NoOutputSpecifiedError } from 'ai';
if (NoOutputSpecifiedError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_NoSuchModelError
description: Learn how to fix AI_NoSuchModelError
---
# AI_NoSuchModelError
This error occurs when a model ID is not found.
## Properties
- `modelId`: The ID of the model that was not found
- `modelType`: The type of model
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_NoSuchModelError` using:
```typescript
import { NoSuchModelError } from 'ai';
if (NoSuchModelError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_NoSuchProviderError
description: Learn how to fix AI_NoSuchProviderError
---
# AI_NoSuchProviderError
This error occurs when a provider ID is not found.
## Properties
- `providerId`: The ID of the provider that was not found
- `availableProviders`: Array of available provider IDs
- `modelId`: The ID of the model
- `modelType`: The type of model
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_NoSuchProviderError` using:
```typescript
import { NoSuchProviderError } from 'ai';
if (NoSuchProviderError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_NoSuchToolError
description: Learn how to fix AI_NoSuchToolError
---
# AI_NoSuchToolError
This error occurs when a model tries to call an unavailable tool.
## Properties
- `toolName`: The name of the tool that was not found
- `availableTools`: Array of available tool names
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_NoSuchToolError` using:
```typescript
import { NoSuchToolError } from 'ai';
if (NoSuchToolError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_NoTranscriptGeneratedError
description: Learn how to fix AI_NoTranscriptGeneratedError
---
# AI_NoTranscriptGeneratedError
This error occurs when no transcript could be generated from the input.
## Properties
- `responses`: Array of responses
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_NoTranscriptGeneratedError` using:
```typescript
import { NoTranscriptGeneratedError } from 'ai';
if (NoTranscriptGeneratedError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_RetryError
description: Learn how to fix AI_RetryError
---
# AI_RetryError
This error occurs when a retry operation fails.
## Properties
- `reason`: The reason for the retry failure
- `lastError`: The most recent error that occurred during retries
- `errors`: Array of all errors that occurred during retry attempts
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_RetryError` using:
```typescript
import { RetryError } from 'ai';
if (RetryError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_TooManyEmbeddingValuesForCallError
description: Learn how to fix AI_TooManyEmbeddingValuesForCallError
---
# AI_TooManyEmbeddingValuesForCallError
This error occurs when too many values are provided in a single embedding call.
## Properties
- `provider`: The AI provider name
- `modelId`: The ID of the embedding model
- `maxEmbeddingsPerCall`: The maximum number of embeddings allowed per call
- `values`: The array of values that was provided
## Checking for this Error
You can check if an error is an instance of `AI_TooManyEmbeddingValuesForCallError` using:
```typescript
import { TooManyEmbeddingValuesForCallError } from 'ai';
if (TooManyEmbeddingValuesForCallError.isInstance(error)) {
// Handle the error
}
```
---
title: ToolCallRepairError
description: Learn how to fix AI SDK ToolCallRepairError
---
# ToolCallRepairError
This error occurs when there is a failure while attempting to repair an invalid tool call.
This typically happens when the AI attempts to fix either
a `NoSuchToolError` or `InvalidToolArgumentsError`.
## Properties
- `originalError`: The original error that triggered the repair attempt (either `NoSuchToolError` or `InvalidToolArgumentsError`)
- `message`: The error message
- `cause`: The underlying error that caused the repair to fail
## Checking for this Error
You can check if an error is an instance of `ToolCallRepairError` using:
```typescript
import { ToolCallRepairError } from 'ai';
if (ToolCallRepairError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_ToolExecutionError
description: Learn how to fix AI_ToolExecutionError
---
# AI_ToolExecutionError
This error occurs when there is a failure during the execution of a tool.
## Properties
- `toolName`: The name of the tool that failed
- `toolArgs`: The arguments passed to the tool
- `toolCallId`: The ID of the tool call that failed
- `message`: The error message
- `cause`: The underlying error that caused the tool execution to fail
## Checking for this Error
You can check if an error is an instance of `AI_ToolExecutionError` using:
```typescript
import { ToolExecutionError } from 'ai';
if (ToolExecutionError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_TypeValidationError
description: Learn how to fix AI_TypeValidationError
---
# AI_TypeValidationError
This error occurs when type validation fails.
## Properties
- `value`: The value that failed validation
- `message`: The error message including validation details
## Checking for this Error
You can check if an error is an instance of `AI_TypeValidationError` using:
```typescript
import { TypeValidationError } from 'ai';
if (TypeValidationError.isInstance(error)) {
// Handle the error
}
```
---
title: AI_UnsupportedFunctionalityError
description: Learn how to fix AI_UnsupportedFunctionalityError
---
# AI_UnsupportedFunctionalityError
This error occurs when functionality is not unsupported.
## Properties
- `functionality`: The name of the unsupported functionality
- `message`: The error message
## Checking for this Error
You can check if an error is an instance of `AI_UnsupportedFunctionalityError` using:
```typescript
import { UnsupportedFunctionalityError } from 'ai';
if (UnsupportedFunctionalityError.isInstance(error)) {
// Handle the error
}
```
---
title: xAI Grok
description: Learn how to use xAI Grok.
---
# xAI Grok Provider
The [xAI Grok](https://x.ai) provider contains language model support for the [xAI API](https://x.ai/api).
## Setup
The xAI Grok provider is available via the `@ai-sdk/xai` module. You can
install it with
{m.role}: {m.content}
))}
{error && An error occurred.
}