{ "id": "nextjs/next-head-element-duplicate", "signature": "Error: Duplicate element found. Only one element is allowed per document.", "signature_zh": "错误：发现重复的 元素。每个文档只允许一个 元素。", "regex": "Error: Duplicate element found", "domain": "nextjs", "category": "build_error", "subcategory": null, "root_cause": "In Next.js app directory, multiple layouts or pages export elements, causing duplicate head tags in the HTML output.", "root_cause_type": "generic", "root_cause_zh": "在 Next.js app 目录中，多个布局或页面导出了 元素，导致 HTML 输出中出现重复的 head 标签。", "versions": [ { "version": "next@13.4.0", "introduced": null, "deprecated": null, "removed": null, "behavior_change": null, "status": "active" }, { "version": "next@14.0.0", "introduced": null, "deprecated": null, "removed": null, "behavior_change": null, "status": "active" }, { "version": "next@14.2.0", "introduced": null, "deprecated": null, "removed": null, "behavior_change": null, "status": "active" } ], "os_specific": {}, "dead_ends": [ { "action": "", "why_fails": "This creates multiple head elements, which is exactly the error. Metadata should be centralized.", "fail_rate": 0.95, "condition": "", "sources": [] }, { "action": "", "why_fails": "next/head is deprecated in the app directory; it causes hydration errors and duplicate head issues.", "fail_rate": 0.85, "condition": "", "sources": [] }, { "action": "", "why_fails": "The build will fail; this is a blocking error that prevents successful compilation.", "fail_rate": 1.0, "condition": "", "sources": [] } ], "workarounds": [ { "action": "Remove all manual tags from layouts and pages. Use generateMetadata in the root layout to set metadata:\n\nexport const metadata = {\n title: 'My App',\n description: 'Description',\n};\n\nThen in child pages, export generateMetadata to override specific values.", "success_rate": 0.95, "how": "Remove all manual tags from layouts and pages. Use generateMetadata in the root layout to set metadata:\n\nexport const metadata = {\n title: 'My App',\n description: 'Description',\n};\n\nThen in child pages, export generateMetadata to override specific values.", "condition": "", "sources": [] }, { "action": "If using a custom root layout, ensure only one tag exists in the root layout.tsx file, and remove any from child components.", "success_rate": 0.9, "how": "If using a custom root layout, ensure only one tag exists in the root layout.tsx file, and remove any from child components.", "condition": "", "sources": [] }, { "action": "For legacy pages using pages directory, keep next/head there but avoid mixing with app directory layouts.", "success_rate": 0.85, "how": "For legacy pages using pages directory, keep next/head there but avoid mixing with app directory layouts.", "condition": "", "sources": [] } ], "workarounds_zh": [ "从布局和页面中移除所有手动 标签。在根布局中使用 generateMetadata 设置元数据：\n\nexport const metadata = {\n title: '我的应用',\n description: '描述',\n};\n\n然后在子页面中导出 generateMetadata 来覆盖特定值。", "如果使用自定义根布局，确保根 layout.tsx 文件中只有一个 标签，并从子组件中移除。", "对于使用 pages 目录的旧页面，保留 next/head，但避免与 app 目录布局混合。" ], "transition_graph": { "leads_to": [], "preceded_by": [], "frequently_confused_with": [] }, "official_doc_url": "https://nextjs.org/docs/app/building-your-application/optimizing/metadata", "official_doc_section": null, "error_code": null, "verification_tier": "ai_generated", "confidence": 0.88, "fix_success_rate": 0.95, "resolvable": "true", "first_seen": "2023-11-20", "last_confirmed": "2024-06-01", "last_updated": "2024-06-01", "evidence_count": 1, "tags": [], "locale": "en", "aliases": [] }