vercel/next.js · error

Warning: viewport meta tags should not be used in _document.

Error message

Warning: viewport meta tags should not be used in _document.js's <Head>. https://nextjs.org/docs/messages/no-document-viewport-meta

What it means

Development-only warning raised inside the custom Head component's render in pages/_document.tsx. It fires when the children of <Head> are inspected and a <meta name="viewport"> element is found (children coming from react-helmet are exempt). _document is rendered once on the server for every page, so per-page viewport configuration there is wrong; it belongs in the App Router metadata viewport export or in pages via next/head in a page.

Source

Thrown at packages/next/src/pages/_document.tsx:675

      head = cssPreloads.concat(otherHeadElements)
    }
    let children: React.ReactNode[] = React.Children.toArray(
      this.props.children
    ).filter(Boolean)
    // show a warning if Head contains <title> (only in development)
    if (process.env.NODE_ENV !== 'production') {
      children = React.Children.map(children, (child: any) => {
        const isReactHelmet = child?.props?.['data-react-helmet']
        if (!isReactHelmet) {
          if (child?.type === 'title') {
            console.warn(
              "Warning: <title> should not be used in _document.js's <Head>. https://nextjs.org/docs/messages/no-document-title"
            )
          } else if (
            child?.type === 'meta' &&
            child?.props?.name === 'viewport'
          ) {
            console.warn(
              "Warning: viewport meta tags should not be used in _document.js's <Head>. https://nextjs.org/docs/messages/no-document-viewport-meta"
            )
          }
        }
        return child
        // @types/react bug. Returned value from .map will not be `null` if you pass in `[null]`
      })!
      if (this.props.crossOrigin)
        console.warn(
          'Warning: `Head` attribute `crossOrigin` is deprecated. https://nextjs.org/docs/messages/doc-crossorigin-deprecated'
        )
    }

    const files: DocumentFiles = getDocumentFiles(
      this.context.buildManifest,
      this.context.__NEXT_DATA__.page
    )

View on GitHub (pinned to 0eb3775416)

Solutions

  1. Move viewport meta tags to the page-level `next/head` (or viewport export in app dir) instead of _document.
Defensive patterns

Strategy: validation

When it happens

Trigger: Thrown at packages/next/src/pages/_document.tsx:675 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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