vercel/next.js · error · Error

<Html> should not be imported outside of pages/_document. Re

Error message

<Html> should not be imported outside of pages/_document.
Read more: https://nextjs.org/docs/messages/no-document-import-in-page

What it means

Context guard in useHtmlContext: a component consumed the Html context (i.e. imported next/document's Html) while rendering outside pages/_document. The provider is only mounted for the document render, so a null context means the Html component leaked into a page or app-render tree.

Source

Thrown at packages/next/src/shared/lib/html-context.shared-runtime.ts:68

  nextConfigOutput?: 'standalone' | 'export'
  nextScriptWorkers?: boolean
  runtime?: ServerRuntime
  hasConcurrentFeatures?: boolean
  largePageDataBytes?: number
  nextFontManifest?: DeepReadonly<NextFontManifest>
  experimentalClientTraceMetadata?: string[]
}

export const HtmlContext = createContext<HtmlProps | undefined>(undefined)
if (process.env.NODE_ENV !== 'production') {
  HtmlContext.displayName = 'HtmlContext'
}

export function useHtmlContext() {
  const context = useContext(HtmlContext)

  if (!context) {
    throw new Error(
      `<Html> should not be imported outside of pages/_document.\n` +
        'Read more: https://nextjs.org/docs/messages/no-document-import-in-page'
    )
  }

  return context
}

View on GitHub (pinned to 0eb3775416)

Solutions

  1. Import <Html> only in pages/_document; remove the import from other files.
Defensive patterns

Strategy: validation

When it happens

Trigger: <Html> from next/document is imported outside pages/_document.

Common situations: Importing next/document's Html component in a regular page or component.

AI-assisted analysis of vercel/next.js@0eb3775416 (2026-08-19). Data as JSON: /api/errors/6f37ba91472c4578. Report an issue: GitHub.