{"record":{"id":"c0fa23ab13e47a5a","repo":"facebook/react","slug":"the-html-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":3808,"sourceCode":" // 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, 'body', formatContext);\n }\n}\n\nfunction pushStartHtml(\n target: Array,\n props: Object,\n renderState: RenderState,\n preambleState: null | PreambleState,\n formatContext: FormatContext,\n): ReactNodeList {\n if (formatContext.insertionMode === ROOT_HTML_MODE) {\n // This is the Document.documentElement\n const preamble = preambleState || renderState.preamble;\n\n if (preamble.htmlChunks) {\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(htmlPreambleContributionChunk);\n }\n\n preamble.htmlChunks = [DOCTYPE];\n return pushStartSingletonElement(\n preamble.htmlChunks,\n props,\n 'html',\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, 'html', formatContext);","sourceCodeStart":3790,"sourceCodeEnd":3826,"githubUrl":"https://github.com/facebook/react/blob/eafeac097ba51e1eab809c07102126bd5f8e5425/packages/react-dom-bindings/src/server/ReactFizzConfigDOM.js#L3790-L3826","documentation":"Thrown by pushStartHtml when a second root-level begins rendering (preamble.htmlChunks already set and insertionMode === ROOT_HTML_MODE). Fizz tracks the single document element in the preamble; a second finds the slot taken and throws, since an HTML document can contain only one root element.","triggerScenarios":"Server-rendering two elements at the root — e.g. a root layout with and a child route or imported component that also returns ..., or concatenating two full-document templates into one tree.","commonSituations":"Framework migrations where a page kept its old wrapper; embedding a complete standalone page (error pages, email templates) inside an app tree; testing utilities that render a full document as the root and also wrap it.","solutions":["Render exactly once at the very root of the server tree","Strip // from any nested page/component and keep only their inner content","If a second full document is truly needed, render it as a separate stream (separate renderToPipeableStream call), not nested"],"exampleFix":"// before\n// layout: {children}\n// page:

\n\n// after: page renders content only\n<>\n

Hello

\n","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Render exactly once as the outermost element of the server tree","Return fragments from nested layouts/pages instead of second documents","Render separate documents as separate streams, never nested"],"tags":["ssr","html","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"}