Chat - Error handling

Handle errors raised by adapters, streams, and history loading through a unified error model.

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

Interactive playground

The demo below lets you toggle a message error and observe the ChatMessageError component rendered under the failed message:

Error propagation

When an adapter method throws, the runtime:

1. Records a ChatError with the appropriate source and code.
2. Surfaces it through ChatBox's built-in error UI, useChat().error, and the onError callback.
3. Marks the error recoverable when applicable (for example, stream disconnects) and retryable when the user can try again.

Both error surfaces are announced to assistive technology: the headless MessageError primitive renders with role="alert", and the Material ChatMessageError card uses aria-live="polite" with aria-atomic="true" so existing errors aren't re-announced on mount.

Handling errors at the application level

Use the onError prop on ChatBox to handle errors at the application level:

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

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

The demo below shows the default error UI surfaced by ChatBox when sendMessage() fails:

Error object structure

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

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

Error codes

Error sources

recoverable vs retryable

• recoverable: the runtime can recover from this error automatically (for example, by reconnecting a dropped stream via reconnectToStream()); see Stream disconnect recovery.
• retryable: the user can try the operation again (for example, by re-sending a failed message).

Accessing the error state

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)}>Dismiss</button>
    </div>
  );
}

Retrying failed messages

When sendMessage() fails, the user's message stays in the thread (optimistic update) and the composer re-enables 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)}>Retry</button>;
}

retry(messageId) looks up the original user message by ID, re-submits it through the adapter's sendMessage(), and replaces any previous error state. retry(messageId) is a no-op while a send or stream is already in flight, and for messages whose role isn't 'user'. The built-in ChatMessageError retry button disables itself in those cases.

The demo below fails the first send attempt, then succeeds when you click Retry:

Error from adapter methods

You don't need to wrap adapter methods in try/catch to surface errors to the runtime, but you should wrap them to log to your observability platform. 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 }) {
  try {
    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!;
  } catch (error) {
    // Log to Sentry, Datadog, or your error-tracking platform
    console.error('Adapter sendMessage failed:', error);
    // Re-throw so the runtime can surface the failure to the user
    throw error;
  }
},

Stream disconnect recovery

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

1. Records a recoverable stream error.
2. Sets the message status to 'error'.
3. Calls onFinish with isDisconnect: true.
4. If reconnectToStream() is implemented on the adapter, makes one attempt to resume the stream.
5. Calls onError only when the disconnect remains unrecovered.

See Reconnecting to streams for details.

Message status and errors

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 send</span>
      )}
    </div>
  );
}

Use the useMessageError(messageId) hook to read a single message's error from your own components.

See also

• Streaming for stream lifecycle and disconnect handling.
• Adapter for the adapter interface and error propagation details.

API

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

• <ChatBox />
• <ChatMessageError />