What causes "Prevent usage of `next/head` in `pages/_document.js`." in oxc-project/oxc?

Replace `import Head from 'next/head'` with `import { Head } from 'next/document'` in `_document.js`.

oxc-project/oxc · warning · OxcDiagnostic

Prevent usage of `next/head` in `pages/_document.js`.

Error message

Prevent usage of `next/head` in `pages/_document.js`.

What it means

Warning from oxlint rule `nextjs/no-head-import-in-document`. Inside `pages/_document.js`, `next/head` does not work: the document is rendered outside the normal page tree, and using `next/head` there can duplicate head output on every request. Next.js provides `Head` from `next/document` for that file, and the rule enforces the distinction.

Source

Thrown at crates/oxc_linter/src/rules/nextjs/no_head_import_in_document.rs:13

use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{
    AstNode,
    context::{ContextHost, LintContext},
    rule::Rule,
};

fn no_head_import_in_document_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Prevent usage of `next/head` in `pages/_document.js`.")
        .with_help("See https://nextjs.org/docs/messages/no-head-import-in-document")
        .with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct NoHeadImportInDocument;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Prevents the usage of `next/head` inside a Next.js document.
    ///
    /// ### Why is this bad?
    ///
    /// Importing `next/head` inside `pages/_document.js` can cause
    /// unexpected issues in your Next.js application.
    ///
    /// ### Examples

View on GitHub (pinned to e1e7af627c)

Solutions

Replace `import Head from 'next/head'` with `import { Head } from 'next/document'` in `_document.js`.
Keep `next/head` imports only in individual pages.

Example fix

// before (pages/_document.js)
import Head from 'next/head';

// after
import { Head } from 'next/document';

Defensive patterns

Strategy: validation

Validate before calling

// next/head imported into the document:
// rg -n "from 'next/head'" pages/_document.*

Prevention

Only two valid head imports: `next/head` in pages, `next/document`'s named `Head` in `_document.js`.
When scaffolding the custom document, start from the official template.
Run oxlint with the nextjs plugin so the wrong import is flagged instantly.

When it happens

Trigger: An import of `next/head` in a file identified as `pages/_document.js`.

Common situations: Copying a page's head import into `_document.js` while scaffolding; IDE auto-import choosing the wrong `Head`.

Related errors

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/23ca771097fd1e67. Report an issue: GitHub.