What causes "Prevent usage of ` ` with `Head` component from `next/document`." in oxc-project/oxc?

Delete the ` ` from `pages/_document.js`.

oxc-project/oxc · warning · OxcDiagnostic

Prevent usage of `<title>` with `Head` component from `next/

Error message

Prevent usage of `<title>` with `Head` component from `next/document`.

What it means

Warning from oxlint rule `nextjs/no-title-in-document-head`. `pages/_document.js` is shared by every route, so a `<title>` inside its `<Head>` pins one title app-wide and fights per-page titles set via `next/head`. The rule reports `<title>` elements placed inside a `Head` imported from `next/document`.

Source

Thrown at crates/oxc_linter/src/rules/nextjs/no_title_in_document_head.rs:12

use oxc_ast::{
    AstKind,
    ast::{ImportDeclarationSpecifier, JSXChild, JSXElementName},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::{GetSpan, Span};

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

fn no_title_in_document_head_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Prevent usage of `<title>` with `Head` component from `next/document`.")
        .with_help("See https://nextjs.org/docs/messages/no-title-in-document-head")
        .with_label(span)
}

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

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Prevent usage of `<title>` with `Head` component from `next/document`.
    ///
    /// ### Why is this bad?
    ///
    /// A `<title>` element should only be used for any `<head>` code that is common for all pages.
    /// Title tags should be defined at the page-level using `next/head` instead.
    ///
    /// ### Examples

View on GitHub (pinned to e1e7af627c)

Solutions

Delete the `<title>` from `pages/_document.js`.
Set titles per page with `next/head`, or with `export const metadata = { title }` in the app router.

Example fix

// before (pages/_document.js)
<Head><title>My App</title></Head>

// after (pages/index.js)
import Head from 'next/head';
<Head><title>Home | My App</title></Head>

Defensive patterns

Strategy: validation

Validate before calling

// title inside the document's Head:
// rg -n -A6 'from .next/document.' pages/_document.* | rg '<title'

Prevention

Titles live per page (`next/head`) or in app-router `metadata`, never in `_document.js`.
When scaffolding the custom document, start from the official template without a title.
Run oxlint with the nextjs plugin in CI to catch a stray title immediately.

When it happens

Trigger: A `<title>` JSX element whose ancestor is a `<Head>` component imported from `next/document` — i.e. inside the custom document.

Common situations: Setting a default site title while scaffolding `_document.js`; misunderstanding that per-page titles must live in each page, not the shared document.

Related errors

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