facebook/docusaurus · error · ReactContextError

Hook is called outside the <DocsVersionProvider>.

Error message

Hook is called outside the <DocsVersionProvider>. 

What it means

Thrown by useDocsVersion() when DocsVersionContext holds null, meaning no <DocsVersionProvider> ancestor rendered with a non-null version. The provider is set up by the docs theme around doc pages to supply the active version metadata; calling useDocsVersion() outside a doc route (navbar, layout, homepage) throws. ReactContextError yields 'Hook useDocsVersion is called outside the <DocsVersionProvider>.'. Note the provider accepts version: PropVersionMetadata | null, but the hook treats null as the error condition.

Source

Thrown at packages/docusaurus-plugin-content-docs/src/client/docsVersion.tsx:33

 * Provide the current version's metadata to your children.
 */
export function DocsVersionProvider({
  children,
  version,
}: {
  children: ReactNode;
  version: PropVersionMetadata | null;
}): ReactNode {
  return <Context.Provider value={version}>{children}</Context.Provider>;
}

/**
 * Gets the version metadata of the current doc page.
 */
export function useDocsVersion(): PropVersionMetadata {
  const version = useContext(Context);
  if (version === null) {
    throw new ReactContextError('DocsVersionProvider');
  }
  return version;
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Only call useDocsVersion() within the docs page subtree (under DocsVersionProvider).
2. For layout components that must work on all pages, use useDocsVersionCandidates() or route-aware hooks that degrade gracefully outside docs.
3. Re-add DocsVersionProvider in any swizzled docs layout.
4. In tests, wrap renders in <DocsVersionProvider version={mockVersion}>.

Example fix

// before
function VersionBadge() {
  const v = useDocsVersion(); // throws on non-doc pages
  return <span>{v.label}</span>;
}
// after: guard by route type, or use a layout-safe hook
function VersionBadge() {
  const route = useRouteContext();
  if (route?.plugin?.name !== 'docusaurus-plugin-content-docs') return null;
  const v = useDocsVersion();
  return <span>{v.label}</span>;
}

import useRouteContext from '@docusaurus/useRouteContext';

function useIsDocRoute() {
  return useRouteContext()?.plugin?.name === 'docusaurus-plugin-content-docs';
}
// if (!useIsDocRoute()) return null; // before calling useDocsVersion()

const isDocRoute = (
  route: ReturnType<typeof useRouteContext>,
): boolean => route?.plugin?.name === 'docusaurus-plugin-content-docs';

When it happens

Trigger: Calling useDocsVersion() in a layout/navbar/footer rendered on non-doc pages; using a version-aware component on the homepage or a blog page; swizzling the docs layout and removing DocsVersionProvider.

Common situations: Reusing a version badge / version-aware component in a global layout; a swizzle of DocPage that dropped the provider; importing a docs-only component into a custom page.

Related errors

• Hook is called outside the <DocsPreferredVersionContextProvi
• Hook is called outside the <DocProvider>.
• Hook is called outside the <DocSidebarItemsExpandedStateProv
• Hook is called outside the <DocsSidebarProvider>.
• Hook is called outside the <BlogPostProvider>.

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/dfc215e8877b8582. Report an issue: GitHub.