facebook/docusaurus · error · Error

HTML minification failed (Terser)

Error message

HTML minification failed (Terser)

What it means

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.

Source

Thrown at packages/docusaurus-bundler/src/minifyHtml.ts:64

  return {
    minify: async function minifyHtmlWithTerser(html) {
      try {
        const code = await terserHtmlMinifier(html, {
          // When enabled => React hydration errors
          removeComments: false,
          removeRedundantAttributes: false,
          removeEmptyAttributes: false,
          sortAttributes: false,
          sortClassName: false,

          removeScriptTypeAttributes: true,
          removeStyleLinkTypeAttributes: true,
          useShortDoctype: true,
          minifyJS: true,
        });
        return {code, warnings: []};
      } catch (err) {
        throw new Error(`HTML minification failed (Terser)`, {
          cause: err,
        });
      }
    },
  };
}

// Minify html with @swc/html
// Not well-documented but fast!
// See https://github.com/swc-project/swc/discussions/9616
async function getSwcMinifier(): Promise<HtmlMinifier> {
  const swcHtmlMinifier = await importSwcHtmlMinifier();
  return {
    minify: async function minifyHtmlWithSwc(html) {
      try {
        const result = await swcHtmlMinifier(Buffer.from(html), {
          // Removing comments can lead to React hydration errors
          // See https://x.com/sebastienlorber/status/1841966927440478577

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Read err.cause for the exact line/column html-minifier-terser flagged and fix the offending markup.
2. Temporarily set environment variable SKIP_HTML_MINIFICATION=true to confirm minification is the culprit and unblock the build.
3. If a specific page is at fault, simplify its custom theme HTML / inline scripts.
4. Consider switching to the SWC minifier via @docusaurus/faster (future.faster) which is more tolerant.

Example fix

# isolate the cause
SKIP_HTML_MINIFICATION=true npm run build
# then fix the markup reported in err.cause

// no inline pre-check; reduce blast radius with the env var:
// process.env.SKIP_HTML_MINIFICATION = 'true' // disables minification entirely

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• HTML minification failed (SWC)
• MDX compilation failed for file ${logger.path(filePath)} Cau
• Copying Docusaurus template name=${source.template.name} fai
• Copying local template path=${source.path} failed!
• Failed to update package.json.

AI-assisted analysis of facebook/docusaurus@3f483e80e3 (2026-08-12). Data as JSON: /api/errors/03de6151aa7d9ceb. Report an issue: GitHub.