{"record":{"id":"03de6151aa7d9ceb","repo":"facebook/docusaurus","slug":"html-minification-failed-terser","errorCode":null,"errorMessage":"HTML minification failed (Terser)","messagePattern":"HTML minification failed \\(Terser\\)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/docusaurus-bundler/src/minifyHtml.ts","lineNumber":64,"sourceCode":"  return {\n    minify: async function minifyHtmlWithTerser(html) {\n      try {\n        const code = await terserHtmlMinifier(html, {\n          // When enabled => React hydration errors\n          removeComments: false,\n          removeRedundantAttributes: false,\n          removeEmptyAttributes: false,\n          sortAttributes: false,\n          sortClassName: false,\n\n          removeScriptTypeAttributes: true,\n          removeStyleLinkTypeAttributes: true,\n          useShortDoctype: true,\n          minifyJS: true,\n        });\n        return {code, warnings: []};\n      } catch (err) {\n        throw new Error(`HTML minification failed (Terser)`, {\n          cause: err,\n        });\n      }\n    },\n  };\n}\n\n// Minify html with @swc/html\n// Not well-documented but fast!\n// See https://github.com/swc-project/swc/discussions/9616\nasync function getSwcMinifier(): Promise<HtmlMinifier> {\n  const swcHtmlMinifier = await importSwcHtmlMinifier();\n  return {\n    minify: async function minifyHtmlWithSwc(html) {\n      try {\n        const result = await swcHtmlMinifier(Buffer.from(html), {\n          // Removing comments can lead to React hydration errors\n          // See https://x.com/sebastienlorber/status/1841966927440478577","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/facebook/docusaurus/blob/3f483e80e326cc646b54b83d564b3f0c4881b9a6/packages/docusaurus-bundler/src/minifyHtml.ts#L46-L82","documentation":"Thrown by the Terser HTML minifier wrapper in @docusaurus/bundler when html-minifier-terser rejects the HTML passed to it during production build (getTerserMinifier). The original error is attached as `cause`. Terser is the default (non-faster) HTML minifier and runs over the rendered static HTML of each route.","triggerScenarios":"Building the site with the default Terser HTML minifier when one page emits HTML that html-minifier-terser cannot process (severely malformed markup, an embedded <script> minifyJS cannot parse, very large input tripping a parser limit).","commonSituations":"A custom theme component emitting invalid HTML (unclosed tags, stray characters inside <script>); an injected third-party widget whose inline JS breaks minifyJS; upgrading html-minifier-terser via a transitive dep and hitting a stricter parser.","solutions":["Read err.cause for the exact line/column html-minifier-terser flagged and fix the offending markup.","Temporarily set environment variable SKIP_HTML_MINIFICATION=true to confirm minification is the culprit and unblock the build.","If a specific page is at fault, simplify its custom theme HTML / inline scripts.","Consider switching to the SWC minifier via @docusaurus/faster (future.faster) which is more tolerant."],"exampleFix":"# isolate the cause\nSKIP_HTML_MINIFICATION=true npm run build\n# then fix the markup reported in err.cause","handlingStrategy":"try-catch","validationCode":"// no inline pre-check; reduce blast radius with the env var:\n// process.env.SKIP_HTML_MINIFICATION = 'true' // disables minification entirely","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep theme HTML well-formed; validate rendered output during development.","Use SKIP_HTML_MINIFICATION=true to isolate minification failures in CI.","After an html-minifier-terser upgrade, run a full build before relying on it."],"tags":["bundler","html-minification","terser","build","wrapped-error"],"backgroundTag":null,"analyzedSha":"3f483e80e326cc646b54b83d564b3f0c4881b9a6","analyzedAt":"2026-08-12T13:25:04.382Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}