What causes "useAI must be used within AIContextProvider" in GitbookIO/gitbook?

Wrap the consuming component (or its page) in (the component exporting the provider shown above the hook) with the required config value.

GitbookIO/gitbook · error · Error

useAI must be used within AIContextProvider

Error message

useAI must be used within AIContextProvider

What it means

Thrown by useAIConfig(), a React hook in the GitBook AI components that reads configuration from an AIContext React context. Like all 'must be used within Provider' errors, it means the hook's useContext call returned null because no AIContextProvider ancestor rendered the provider, so there is no config to return.

Source

Thrown at packages/gitbook/src/components/AI/useAI.tsx:71

     */
    icon: ReactNode;
};

const AIContext = React.createContext<AIConfig | null>(null);

export function AIContextProvider(props: React.PropsWithChildren<AIConfig>): React.ReactElement {
    const { aiMode, trademark, suggestions, greeting, assistantName, children } = props;
    const value = React.useMemo(
        () => ({ aiMode, trademark, suggestions, greeting, assistantName }),
        [aiMode, trademark, suggestions, greeting, assistantName]
    );
    return <AIContext.Provider value={value}>{children}</AIContext.Provider>;
}

export function useAIConfig(): AIConfig {
    const ctx = React.useContext(AIContext);
    if (!ctx) {
        throw new Error('useAI must be used within AIContextProvider');
    }
    return ctx;
}

type AIContext = {
    config: AIConfig;
    assistants: Assistant[];
};

/**
 * Unified assistants list combining the built-in GitBook Assistant (when enabled)
 * with any custom assistants registered at runtime.
 */
export function useAI(): AIContext {
    const config = useAIConfig();
    const chat = useAIChatState();
    const chatController = useAIChatController();
    const language = useLanguage();

View on GitHub (pinned to db67585ee2)

Solutions

Wrap the consuming component (or its page) in <AIContextProvider> (the component exporting the provider shown above the hook) with the required config value.
If it happens in tests, render the consumer inside the provider in your test wrapper.
Ensure the provider is actually an ancestor in the same React tree (not a sibling or a separate root).
For compound AI components, use the top-level exported component that internally sets up the provider rather than consuming hooks directly.

Example fix

// before
export function MyAssistant() {
    const config = useAIConfig(); // throws
    ...
}

// after
export function MyAssistant() {
    return (
        <AIContextProvider config={config}>
            <MyAssistantInner />
        </AIContextProvider>
    );
}
function MyAssistantInner() {
    const config = useAIConfig(); // ok
    ...
}

Defensive patterns

Strategy: type-guard

Validate before calling

// Ensure the provider is an ancestor before rendering consumers:
<MyAIApp>
    <AIContextProvider config={config}>
        <ConsumesUseAIConfig />
    </AIContextProvider>
</MyAIApp>

Type guard

function hasAIConfig(ctx: AIConfig | null): ctx is AIConfig {
    return ctx !== null;
}

function useOptionalAIConfig(): AIConfig | null {
    return React.useContext(AIContext); // null-safe alternative to useAIConfig
}

Try / catch

try {
    const config = useAIConfig();
} catch {
    // note: hooks that throw still ran; prefer structural fixes over catching
}

Prevention

Never call context-consuming hooks outside the documented provider tree.
Create a nullable variant hook (useContext directly) when a component might render provider-less.
Wrap test renders with the provider fixture.

When it happens

Trigger: Calling useAIConfig() in a component rendered outside <AIContextProvider>...</AIContextProvider>; rendering the provider and consumer in different React roots; memoization or portal techniques that move the consumer outside the provider's subtree; forgetting to wrap a custom page/section that uses AI components.

Common situations: Adding AI components to a custom layout or standalone test render without the provider; unit tests (React Testing Storybook / RTL) rendering the consumer directly; refactors that lifted the provider out of a subtree that still consumes it.

Related errors

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