oxc-project/oxc · warning · OxcDiagnostic
Do not include multiple instances of `<Head/>`
Error message
Do not include multiple instances of `<Head/>`
What it means
Warning from oxlint rule `nextjs/no-duplicate-head`. In `pages/_document.js`, each `<Head>` imported from `next/document` produces its own server-rendered head context; more than one yields duplicate or conflicting head markup. The rule counts `Head` usages in the custom document and, when there are two or more, reports every occurrence with a label on each.
Source
Thrown at crates/oxc_linter/src/rules/nextjs/no_duplicate_head.rs:10
use oxc_ast::AstKind;
use oxc_diagnostics::{LabeledSpan, OxcDiagnostic};
use oxc_macros::declare_oxc_lint;
use oxc_semantic::AstNode;
use oxc_span::GetSpan;
use crate::{context::LintContext, rule::Rule};
fn no_duplicate_head(labels: Vec<LabeledSpan>) -> OxcDiagnostic {
OxcDiagnostic::warn("Do not include multiple instances of `<Head/>`")
.with_help("Only use a single `<Head />` component in your custom document in `pages/_document.js`. See: https://nextjs.org/docs/messages/no-duplicate-head")
.with_labels(labels)
}
#[derive(Debug, Default, Clone)]
pub struct NoDuplicateHead;
declare_oxc_lint!(
/// ### What it does
///
/// Prevent duplicate usage of `<Head>` in `pages/_document.js`.
///
/// ### Why is this bad?
///
/// This can cause unexpected behavior in your application.
///
/// ### Examples
///
/// Examples of **incorrect** code for this rule:View on GitHub (pinned to e1e7af627c)
Solutions
- Merge the children of every `<Head>` block into a single `<Head>` in `_document.js`.
- Keep only document-wide tags (charset, viewport) there; move page-specific tags to `next/head` in each page.
Example fix
// before
<Html>
<Head><meta charSet="utf-8" /></Head>
<body><Main /><NextScript />
<Head><title>extra</title></Head>
</body>
</Html>
// after
<Html>
<Head><meta charKey="utf-8" /><title>extra</title></Head>
<body><Main /><NextScript /></body>
</Html> Defensive patterns
Strategy: validation
Validate before calling
// count Head blocks in the custom document: // rg -c '<Head' pages/_document.tsx # any count > 1 needs merging
Prevention
- Keep exactly one `<Head>` per custom document; treat a second as a merge task.
- Put page-specific tags in that page's `next/head`, never in `_document.js`.
- Lint `_document.js` in CI with the nextjs plugin.
When it happens
Trigger: Two or more `<Head>...</Head>` elements (from `next/document`) rendered anywhere in `pages/_document.js`, including inside fragments or conditionals.
Common situations: Splitting the document into sections and giving each its own `<Head>`; pasting a meta block into a second Head; merging markup from two tutorials.
Related errors
- Do not use `<head>` element. Use `<Head />` from `next/head`
- Prevent usage of `<title>` with `Head` component from `next/
- next/script's `beforeInteractive` strategy should not be use
- `<Document />` from `next/document` should not be imported o
- Prevent usage of `next/head` in `pages/_document.js`.
AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20).
Data as JSON: /api/errors/db486f2613d7edae.
Report an issue: GitHub.