, <meta>, <link> hoist automatically to it)","Search the tree for all <head> occurrences and delete the duplicates","If multiple modules need head content, hoist individual tags (<title>, <meta>) instead of a second <head>"],"exampleFix":"// before (root layout)\n<html><head>...</head><body>{children}</body></html>\n// plus a page also rendering <head>...</head>\n\n// after: head only in the root layout\n// page.jsx\n<>\n <title>Page

{"record":{"id":"090715e27cd91de7","repo":"facebook/react","slug":"the-head-tag-may-only-be-rendered-once","errorCode":null,"errorMessage":"The `` tag may only be rendered once.","messagePattern":"The `` tag may only be rendered once\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/react-dom-bindings/src/server/ReactFizzConfigDOM.js","lineNumber":3740,"sourceCode":"// These are used by the client if we clear a boundary and we find these, then we\n// also clear the singleton as well.\nconst headPreambleContributionChunk = stringToPrecomputedChunk('');\nconst bodyPreambleContributionChunk = stringToPrecomputedChunk('');\nconst htmlPreambleContributionChunk = stringToPrecomputedChunk('');\n\nfunction pushStartHead(\n target: Array,\n props: Object,\n renderState: RenderState,\n preambleState: null | PreambleState,\n formatContext: FormatContext,\n): ReactNodeList {\n if (formatContext.insertionMode < HTML_MODE) {\n // This is the Document.head and should be part of the preamble\n const preamble = preambleState || renderState.preamble;\n\n if (preamble.headChunks) {\n throw new Error(`The ${'``'} tag may only be rendered once.`);\n }\n\n // Insert a marker in the body where the contribution to the head was in case we need to clear it.\n if (preambleState !== null) {\n target.push(headPreambleContributionChunk);\n }\n\n preamble.headChunks = [];\n return pushStartSingletonElement(\n preamble.headChunks,\n props,\n 'head',\n formatContext,\n );\n } else {\n // This is deep and is likely just an error. we emit it inline though.\n // Validation should warn that this tag is the the wrong spot.\n return pushStartGenericElement(target, props, 'head', formatContext);","sourceCodeStart":3722,"sourceCodeEnd":3758,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react-dom-bindings/src/server/ReactFizzConfigDOM.js#L3722-L3758","documentation":"Thrown by pushStartHead when a second document-level begins rendering. The first at document position stores its chunks on the request's preamble (preamble.headChunks); a second one finds that slot occupied and throws, because the HTML document model allows exactly one head. This check only applies while insertionMode < HTML_MODE, i.e. heads rendered in the document preamble position rather than inside body content.","triggerScenarios":"Server-rendering a tree that contains twice at the top level — e.g. a root layout rendering ... while a nested layout/route also renders , or two components each emitting their own before the body starts.","commonSituations":"Framework layouts where both the shell and a page try to own ; adopting a head-manager library alongside an explicit ; refactors that moved a head-rendering component into a route rendered together with an existing one.","solutions":["Render exactly once, in the root layout, and let other components contribute via hoistable metadata (, <meta>, <link> hoist automatically to it)","Search the tree for all <head> occurrences and delete the duplicates","If multiple modules need head content, hoist individual tags (<title>, <meta>) instead of a second <head>"],"exampleFix":"// before (root layout)\n<html><head>...</head><body>{children}</body></html>\n// plus a page also rendering <head>...</head>\n\n// after: head only in the root layout\n// page.jsx\n<>\n <title>Page\n \n","handlingStrategy":"validation","validationCode":"// enforce a single across the app: only the root layout renders it\nlet headRendered = false;\nfunction DocumentHead() {\n if (headRendered) throw new Error('Only one allowed; hoist /<meta> instead');\n headRendered = true;\n return <head />;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Render <head> once, in the root layout only","Let metadata components hoist <title>/<meta>/<link> instead of wrapping them in their own <head>","Codemod/grep for '<head' across layouts and pages during framework migrations"],"tags":["ssr","head","preamble","document-structure"],"backgroundTag":"duplicate-document-element","analyzedSha":"eafeac097ba51e1eab809c07102126bd5f8e5425","analyzedAt":"2026-08-21T22:01:08.818Z","schemaVersion":2},"datasetVersion":"2026-08-21T23:17:16.201Z"}