Error Handling - MUI X

How errors are captured, surfaced, and recovered from across the chat runtime.

The chat runtime captures errors from adapters, streams, and history loading, and surfaces them through a unified error model. You do not need to catch errors inside adapter methods — the runtime handles them for you.

Every error recorded by the runtime is represented as a ChatError:

interface ChatError {
code: ChatErrorCode;
message: string;
source: ChatErrorSource;
recoverable: boolean;
retryable?: boolean;
details?: Recordstring, unknown>;
}

When an adapter method throws, the runtime:

Handle errors at the application level using the onError prop on ChatBox:

ChatBox
adapter={adapter}
onError={(error) => {
console.error(`[Chat error] ${error.source}: ${error.message}`);

// Report to your error tracking service
errorTracker.capture(error);
}}
/>

Styled with your active MUI theme

Hello! I am styled using your active Material UI theme. Try sending a message.

Great — the bubble colors come from palette.primary and the typography from the theme.

The useChat() hook exposes the current error:

import { useChat } from '@mui/x-chat/headless';

function ErrorBanner() {
const { error, setError } = useChat();

if (!error) return null;

return (
div role="alert">
p>{error.message}p>
button onClick={() => setError(null)}>Dismissbutton>
div>
);
}

When sendMessage() fails, the user's message is still displayed in the thread (optimistic update) and the composer is re-enabled so the user can try again.

The useChat() hook provides a retry method that re-sends the message associated with a given message ID:

import { useChat } from '@mui/x-chat/headless';

function RetryButton({ messageId }: { messageId: string }) {
const { retry } = useChat();

return button onClick={() => retry(messageId)}>Retrybutton>;
}

retry() looks up the original user message by ID, re-submits it through the adapter's sendMessage(), and replaces any previous error state.

You do not need to wrap adapter methods in try/catch — the runtime handles all thrown errors. If you want to transform or enrich an error before the runtime sees it, throw a plain Error with a custom message. The runtime wraps it in a ChatError with source 'adapter':

async sendMessage({ message, signal }) {
const res = await fetch('/api/chat', {
method: 'POST',
body: JSON.stringify({ message }),
signal,
});

if (!res.ok) {
throw new Error(`Server responded with ${res.status}`);
}

return res.body!;
},

If a stream closes without a terminal chunk (finish or abort), the runtime:

See Streaming—Reconnecting to streams for implementation details.

The message status field reflects error states:

Components can use the status field to conditionally render error indicators:

function MessageBubble({ message }: { message: ChatMessage }) {
return (
div>
{message.parts.map((part) => /* render parts */)}
{message.status === 'error' && (
span className="error-badge">Failed to sendspan>
)}
div>
);
}

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

Was this page helpful?

•

•

Contents