Error handling for AI chat (#3411)

nolannbiron · web-flow · commit bc1eca815e75 · 2025-07-03T14:26:40.000+02:00
diff --git a/.changeset/cold-toys-film.md b/.changeset/cold-toys-film.md
@@ -0,0 +1,5 @@
+---
+'gitbook': patch
+---
+
+Error handling for AI Chat
diff --git a/packages/gitbook/src/components/AI/useAIChat.tsx b/packages/gitbook/src/components/AI/useAIChat.tsx
@@ -38,6 +38,13 @@ export type AIChatState = {
      * If true, the session is in progress.
      */
     loading: boolean;
+
+    /**
+     * Set to true when an error occurred while communicating with the server. When
+     * this flag is true, the chat input should be read-only and the UI should
+     * display an error alert. Clearing the conversation will reset this flag.
+     */
+    error: boolean;
 };
 
 export type AIChatController = {
@@ -68,6 +75,7 @@ const globalState = zustand.create<{
             messages: [],
             followUpSuggestions: [],
             loading: false,
+            error: false,
         },
         setState: (fn) => set((state) => ({ state: { ...state.state, ...fn(state.state) } })),
     };
@@ -100,6 +108,7 @@ export function useAIChatController(): AIChatController {
                     messages: [],
                     followUpSuggestions: [],
                     responseId: null,
+                    error: false,
                 })),
             postMessage: async (input: { message: string }) => {
                 trackEvent({ type: 'ask_question', query: input.message });
@@ -121,59 +130,70 @@ export function useAIChatController(): AIChatController {
                         ],
                         followUpSuggestions: [],
                         loading: true,
+                        error: false,
                     };
                 });
 
-                const stream = await streamAIChatResponse({
-                    message: input.message,
-                    messageContext: messageContextRef.current,
-                    previousResponseId: globalState.getState().state.responseId ?? undefined,
-                });
-
-                for await (const data of stream) {
-                    if (!data) continue;
-
-                    const event = data.event;
-
-                    switch (event.type) {
-                        case 'response_finish': {
-                            setState((state) => ({
-                                ...state,
-                                responseId: event.responseId,
-                                // Mark as not loading when the response is finished
-                                // Even if the stream might continue as we receive 'response_followup_suggestion'
-                                loading: false,
-                            }));
-                            break;
-                        }
-                        case 'response_followup_suggestion': {
-                            setState((state) => ({
-                                ...state,
-                                followUpSuggestions: [
-                                    ...state.followUpSuggestions,
-                                    ...event.suggestions,
-                                ],
-                            }));
-                            break;
+                try {
+                    const stream = await streamAIChatResponse({
+                        message: input.message,
+                        messageContext: messageContextRef.current,
+                        previousResponseId: globalState.getState().state.responseId ?? undefined,
+                    });
+
+                    for await (const data of stream) {
+                        if (!data) continue;
+
+                        const event = data.event;
+
+                        switch (event.type) {
+                            case 'response_finish': {
+                                setState((state) => ({
+                                    ...state,
+                                    responseId: event.responseId,
+                                    // Mark as not loading when the response is finished
+                                    // Even if the stream might continue as we receive 'response_followup_suggestion'
+                                    loading: false,
+                                    error: false,
+                                }));
+                                break;
+                            }
+                            case 'response_followup_suggestion': {
+                                setState((state) => ({
+                                    ...state,
+                                    followUpSuggestions: [
+                                        ...state.followUpSuggestions,
+                                        ...event.suggestions,
+                                    ],
+                                }));
+                                break;
+                            }
                         }
+
+                        setState((state) => ({
+                            ...state,
+                            messages: [
+                                ...state.messages.slice(0, -1),
+                                {
+                                    role: AIMessageRole.Assistant,
+                                    content: data.content,
+                                },
+                            ],
+                        }));
                     }
 
                     setState((state) => ({
                         ...state,
-                        messages: [
-                            ...state.messages.slice(0, -1),
-                            {
-                                role: AIMessageRole.Assistant,
-                                content: data.content,
-                            },
-                        ],
+                        loading: false,
+                        error: false,
+                    }));
+                } catch {
+                    setState((state) => ({
+                        ...state,
+                        loading: false,
+                        error: true,
                     }));
                 }
-
-                setState((state) => ({
-                    ...state,
-                    loading: false,
-                }));
             },
         };
     }, [messageContextRef, setState, trackEvent]);
diff --git a/packages/gitbook/src/components/AIChat/AIChat.tsx b/packages/gitbook/src/components/AIChat/AIChat.tsx
@@ -3,7 +3,12 @@
 import { t, tString, useLanguage } from '@/intl/client';
 import { Icon } from '@gitbook/icons';
 import React from 'react';
-import { type AIChatState, useAIChatController, useAIChatState } from '../AI/useAIChat';
+import {
+    type AIChatController,
+    type AIChatState,
+    useAIChatController,
+    useAIChatState,
+} from '../AI/useAIChat';
 import { useNow } from '../hooks';
 import { Button } from '../primitives';
 import { DropdownMenu, DropdownMenuItem } from '../primitives/DropdownMenu';
@@ -159,7 +164,9 @@ export function AIChatWindow(props: { chat: AIChatState }) {
                                     {t(language, 'ai_chat_assistant_description')}
                                 </p>
                             </div>
-                            <AIChatSuggestedQuestions chatController={chatController} />
+                            {!chat.error ? (
+                                <AIChatSuggestedQuestions chatController={chatController} />
+                            ) : null}
                         </div>
                     ) : (
                         <AIChatMessages chat={chat} lastUserMessageRef={lastUserMessageRef} />
@@ -169,11 +176,18 @@ export function AIChatWindow(props: { chat: AIChatState }) {
                     ref={inputRef}
                     className="absolute inset-x-0 bottom-0 mr-2 flex flex-col gap-4 bg-gradient-to-b from-transparent to-50% to-tint-base/9 p-4 pr-2"
                 >
-                    <AIChatFollowupSuggestions chat={chat} chatController={chatController} />
+                    {/* Display an error banner when something went wrong. */}
+                    {chat.error ? (
+                        <AIChatError chatController={chatController} />
+                    ) : (
+                        <AIChatFollowupSuggestions chat={chat} chatController={chatController} />
+                    )}
+
                     <AIChatInput
                         value={input}
                         onChange={setInput}
-                        disabled={chat.loading}
+                        loading={chat.loading}
+                        disabled={chat.loading || chat.error}
                         onSubmit={() => {
                             chatController.postMessage({ message: input });
                             setInput('');
@@ -184,3 +198,29 @@ export function AIChatWindow(props: { chat: AIChatState }) {
         </div>
     );
 }
+
+function AIChatError(props: { chatController: AIChatController }) {
+    const language = useLanguage();
+    const { chatController } = props;
+
+    return (
+        <div className="flex flex-wrap justify-between gap-2 rounded-md bg-danger p-3 text-danger text-sm ring-1 ring-danger">
+            <div className="flex items-center gap-2">
+                <Icon icon="exclamation-triangle" className="size-3.5" />
+                <span className="flex items-center gap-1">{t(language, 'ai_chat_error')}</span>
+            </div>
+            <div className="flex justify-end">
+                <Button
+                    variant="blank"
+                    size="small"
+                    icon="refresh"
+                    label={tString(language, 'unexpected_error_retry')}
+                    onClick={() => {
+                        chatController.clear();
+                    }}
+                    className="!text-danger hover:bg-danger-5"
+                />
+            </div>
+        </div>
+    );
+}
diff --git a/packages/gitbook/src/components/AIChat/AIChatInput.tsx b/packages/gitbook/src/components/AIChat/AIChatInput.tsx
@@ -7,11 +7,15 @@ import { Tooltip } from '../primitives/Tooltip';
 
 export function AIChatInput(props: {
     value: string;
-    disabled: boolean;
+    disabled?: boolean;
+    /**
+     * When true, the input is disabled
+     */
+    loading: boolean;
     onChange: (value: string) => void;
     onSubmit: (value: string) => void;
 }) {
-    const { value, onChange, onSubmit, disabled } = props;
+    const { value, onChange, onSubmit, disabled, loading } = props;
 
     const language = useLanguage();
 
@@ -38,7 +42,8 @@ export function AIChatInput(props: {
         <div className="relative flex flex-col overflow-hidden circular-corners:rounded-2xl rounded-corners:rounded-md bg-tint-base/9 ring-1 ring-tint-subtle backdrop-blur-lg transition-all depth-subtle:has-[textarea:focus]:shadow-lg has-[textarea:focus]:ring-2 has-[textarea:focus]:ring-primary-hover contrast-more:bg-tint-base">
             <textarea
                 ref={inputRef}
-                disabled={disabled}
+                disabled={disabled || loading}
+                data-loading={loading}
                 className={tcls(
                     'resize-none',
                     'focus:outline-none',
@@ -55,7 +60,9 @@ export function AIChatInput(props: {
                     'disabled:bg-tint-subtle',
                     'delay-300',
                     'disabled:delay-0',
-                    'disabled:cursor-progress'
+                    'disabled:cursor-not-allowed',
+                    'data-[loading=true]:cursor-progress',
+                    'data-[loading=true]:opacity-50'
                 )}
                 value={value}
                 rows={1}
diff --git a/packages/gitbook/src/components/AIChat/AIChatMessages.tsx b/packages/gitbook/src/components/AIChat/AIChatMessages.tsx
@@ -34,7 +34,7 @@ export function AIChatMessages(props: {
                     >
                         {message.content ? (
                             message.content
-                        ) : (
+                        ) : chat.loading ? (
                             <div className="flex w-full animate-[fadeIn_500ms_both] flex-wrap gap-2">
                                 {Array.from({ length: 7 }).map((_, index) => (
                                     <div
@@ -47,7 +47,7 @@ export function AIChatMessages(props: {
                                     />
                                 ))}
                             </div>
-                        )}
+                        ) : null}
                     </div>
                 );
             })}
diff --git a/packages/gitbook/src/intl/translations/de.ts b/packages/gitbook/src/intl/translations/de.ts
@@ -74,6 +74,7 @@ export const de = {
     ai_chat_thinking: 'Denke nach...',
     ai_chat_working: 'Arbeite...',
     ai_chat_context_badge: 'KI',
+    ai_chat_error: 'Etwas ist schief gelaufen.',
     ai_chat_context_title: 'Basierend auf Ihrem Kontext',
     ai_chat_context_description:
         'Der Docs-Assistent verwendet KI und Ihren Kontext, um Antworten zu generieren und Aktionen durchzuführen.',
diff --git a/packages/gitbook/src/intl/translations/en.ts b/packages/gitbook/src/intl/translations/en.ts
@@ -49,7 +49,7 @@ export const en = {
     notfound: "The page you are looking for doesn't exist.",
     unexpected_error_title: 'An error occurred',
     unexpected_error: 'Sorry, an unexpected error has occurred. Please try again later.',
-    unexpected_error_retry: 'Retry',
+    unexpected_error_retry: 'Try again',
     pdf_download: 'Export as PDF',
     pdf_goback: 'Go back to content',
     pdf_print: 'Print or Save as PDF',
@@ -72,6 +72,7 @@ export const en = {
     ai_chat_thinking: 'Thinking...',
     ai_chat_working: 'Working...',
     ai_chat_context_badge: 'AI',
+    ai_chat_error: 'Something went wrong.',
     ai_chat_context_title: 'Based on your context',
     ai_chat_context_description:
         'Docs Assistant uses AI and your context to generate answers and perform actions.',
diff --git a/packages/gitbook/src/intl/translations/es.ts b/packages/gitbook/src/intl/translations/es.ts
@@ -76,6 +76,7 @@ export const es: TranslationLanguage = {
     ai_chat_thinking: 'Pensando...',
     ai_chat_working: 'Trabajando...',
     ai_chat_context_badge: 'IA',
+    ai_chat_error: 'Algo salió mal.',
     ai_chat_context_title: 'Basado en tu contexto',
     ai_chat_context_description:
         'El Asistente de Docs usa IA y tu contexto para generar respuestas y realizar acciones.',
diff --git a/packages/gitbook/src/intl/translations/fr.ts b/packages/gitbook/src/intl/translations/fr.ts
@@ -74,6 +74,7 @@ export const fr: TranslationLanguage = {
     ai_chat_thinking: 'Réfléchit...',
     ai_chat_working: 'Travaille...',
     ai_chat_context_badge: 'IA',
+    ai_chat_error: 'Une erreur est survenue.',
     ai_chat_context_title: 'Basé sur votre contexte',
     ai_chat_context_description:
         "L'Assistant Docs utilise l'IA et votre contexte pour générer des réponses et effectuer des actions.",
diff --git a/packages/gitbook/src/intl/translations/ja.ts b/packages/gitbook/src/intl/translations/ja.ts
@@ -74,6 +74,7 @@ export const ja: TranslationLanguage = {
     ai_chat_thinking: '考え中...',
     ai_chat_working: '作業中...',
     ai_chat_context_badge: 'AI',
+    ai_chat_error: '何らかのエラーが発生しました。',
     ai_chat_context_title: 'あなたのコンテキストに基づいて',
     ai_chat_context_description:
         'ドキュメントアシスタントはAIとあなたのコンテキストを使用して回答を生成し、アクションを実行します。',
diff --git a/packages/gitbook/src/intl/translations/nl.ts b/packages/gitbook/src/intl/translations/nl.ts
@@ -74,6 +74,7 @@ export const nl: TranslationLanguage = {
     ai_chat_thinking: 'Denkt na...',
     ai_chat_working: 'Werkt...',
     ai_chat_context_badge: 'AI',
+    ai_chat_error: 'Er is iets misgegaan.',
     ai_chat_context_title: 'Gebaseerd op je context',
     ai_chat_context_description:
         'De Docs Assistent gebruikt AI en je context om antwoorden te genereren en acties uit te voeren.',
diff --git a/packages/gitbook/src/intl/translations/no.ts b/packages/gitbook/src/intl/translations/no.ts
@@ -74,6 +74,7 @@ export const no: TranslationLanguage = {
     ai_chat_thinking: 'Tenker...',
     ai_chat_working: 'Arbeider...',
     ai_chat_context_badge: 'AI',
+    ai_chat_error: 'Noe gikk galt.',
     ai_chat_context_title: 'Basert på din kontekst',
     ai_chat_context_description:
         'Docs-assistenten bruker AI og din kontekst til å generere svar og utføre handlinger.',
diff --git a/packages/gitbook/src/intl/translations/pt-br.ts b/packages/gitbook/src/intl/translations/pt-br.ts
@@ -74,6 +74,7 @@ export const pt_br = {
     ai_chat_thinking: 'Pensando...',
     ai_chat_working: 'Trabalhando...',
     ai_chat_context_badge: 'IA',
+    ai_chat_error: 'Algo deu errado.',
     ai_chat_context_title: 'Baseado no seu contexto',
     ai_chat_context_description:
         'O Assistente de Docs usa IA e seu contexto para gerar respostas e realizar ações.',
diff --git a/packages/gitbook/src/intl/translations/zh.ts b/packages/gitbook/src/intl/translations/zh.ts
@@ -72,6 +72,7 @@ export const zh: TranslationLanguage = {
     ai_chat_thinking: '思考中...',
     ai_chat_working: '工作中...',
     ai_chat_context_badge: 'AI',
+    ai_chat_error: '出了些问题。',
     ai_chat_context_title: '基于您的上下文',
     ai_chat_context_description: '文档助手使用人工智能和您的上下文来生成答案并执行操作。',
     ai_chat_context_pages_youve_read: '您已阅读的页面',

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'gitbook': patch
 +---
++
 +Error handling for AI Chat