GitbookIO/gitbook · error · Error

The AI Assistant is not enabled for this site.

Error message

The AI Assistant is not enabled for this site.

What it means

Thrown by the streamAIChatResponse server action when the site's AI chat feature is disabled. The action fetches the site context and checks customization.ai.mode with isAIChatEnabled; unless the mode explicitly enables chat, it refuses before ever contacting the streaming API. It is a configuration gate, not a runtime failure.

Source

Thrown at packages/gitbook/src/components/AI/server-actions/chat.ts:46

    session,
    options,
}: {
    message?: string;
    messageContext: AIMessageContext;
    previousResponseId?: string;
    toolCall?: AIToolCallResult;
    tools?: AIToolDefinition[];
    session: SiteInsightsSession;
    options?: RenderAIMessageOptions;
}) {
    const { stream } = await traceErrorOnly('AI.streamAIChatResponse', async () => {
        const context = await getServerActionBaseContext({
            isEmbeddable: options?.asEmbeddable,
        });

        const siteContext = await fetchServerActionSiteContext(context);
        if (!isAIChatEnabled(siteContext.customization.ai.mode)) {
            throw new Error('The AI Assistant is not enabled for this site.');
        }

        const siteURLData = await getSiteURLDataFromMiddleware();

        const api = await context.dataFetcher.api();
        const rawStream = api.orgs.streamAiResponseInSite(
            siteURLData.organization,
            siteURLData.site,
            {
                input: message
                    ? [
                          {
                              role: AIMessageRole.User,
                              content: message,
                              context: messageContext,
                          },
                      ]
                    : [],

View on GitHub (pinned to db67585ee2)

Solutions

  1. Enable the AI Assistant (chat mode) for the space/site in GitBook customization settings (customization.ai.mode supporting chat).
  2. If you render chat UI conditionally, gate it on the same isAIChatEnabled(customization.ai.mode) check used server-side so the action is never invoked when disabled.
  3. Verify you're hitting the intended site: wrong org/site URL data leads to a site context whose AI is off.
  4. After enabling, clear/refetch cached site context so the new mode is visible to the server action.

Example fix

// before
<button onClick={() => streamAIChatResponse({ messages })}>Ask</button>

// after
const chatEnabled = isAIChatEnabled(customization.ai.mode);
{chatEnabled && (
    <button onClick={() => streamAIChatResponse({ messages })}>Ask</button>
)}
Defensive patterns

Strategy: validation

Validate before calling

import { isAIChatEnabled } from './ai';

const canChat = isAIChatEnabled(customization.ai.mode);
if (!canChat) {
    renderDisabledState();
} else {
    streamAIChatResponse({ messages });
}

Type guard

const aiModeEnablesChat = (
    mode: string | undefined
): mode is 'chat' | 'search-and-chat' => isAIChatEnabled(mode);

Try / catch

try {
    await streamAIChatResponse(options);
} catch (error) {
    if (error instanceof Error && error.message.includes('not enabled')) {
        showFeatureDisabledNotice();
        return;
    }
    throw error;
}

Prevention

When it happens

Trigger: Invoking the AI chat server action on a site whose customization.ai.mode is 'disabled' or set to a search-only mode (e.g. 'search' instead of 'chat'); embedding the assistant on a site where the AI feature was never turned on in GitBook space settings; the customization not yet propagated after toggling AI on.

Common situations: Self-hosting or embedding the GitBook app against an org/site where AI wasn't enabled; changing the AI customization mode to 'search' while UI components still render the chat entry point; caching serving a stale site customization after the setting changed.

Related errors

AI-assisted analysis of GitbookIO/gitbook@db67585ee2 (2026-08-28). Data as JSON: /api/errors/1caf477f9a9b1cdc. Report an issue: GitHub.