GitbookIO/gitbook · error · Error

This component must be used within a <GitBookProvider />

Error message

This component must be used within a <GitBookProvider />

What it means

Thrown by useGitBook from @gitbook/embed react bindings when React.useContext(GitBookContext) returns null, meaning no <GitBookProvider> wraps the consuming component. The hook has no fallback, so any useGitBook() call outside the provider fails at render time. This is the standard React context-missing error pattern.

Source

Thrown at packages/embed/src/react/GitBookProvider.tsx:33

        () => ({
            siteURL,
        }),
        [siteURL]
    );

    const client = React.useMemo(() => createGitBook(options), [options]);

    return <GitBookContext.Provider value={client}>{children}</GitBookContext.Provider>;
}

/**
 * Hook to access the GitBook client.
 */
export function useGitBook() {
    const context = React.useContext(GitBookContext);

    if (!context) {
        throw new Error('This component must be used within a <GitBookProvider />');
    }

    return context;
}

View on GitHub (pinned to db67585ee2)

Solutions

1. Wrap the component tree (or at least all components using useGitBook) with <GitBookProvider>
2. Verify the provider actually wraps the component (check JSX tree, not module imports)
3. If duplicates of @gitbook/embed exist in node_modules, dedupe them so provider and consumer share one module instance
4. In tests/stories, wrap the render in a <GitBookProvider> decorator or mock the hook

Example fix

// before
function App() {
    return <MyComponent />; // MyComponent calls useGitBook()
}

// after
function App() {
    return (
        <GitBookProvider>
            <MyComponent />
        </GitBookProvider>
    );
}

When it happens

Trigger: Calling useGitBook() in a component rendered outside the <GitBookProvider> tree; rendering the provider and consumer in separate React roots; multiple copies of @gitbook/embed so the context object identity differs between provider and consumer.

Common situations: Adding a component that uses useGitBook to a page where the provider wasn't added; provider mounted in one root (e.g. portal or separate createRoot) while the consumer is in another; version mismatch or duplicate package installs causing two different GitBookContext instances; consuming the hook in a story/test without wrapping in the provider.

Related errors

• useAI must be used within AIContextProvider
• useAIChatController must be used within an AIChatProvider

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