facebook/docusaurus · error · Error

HTML minification failed (SWC)

Error message

HTML minification failed (SWC)

What it means

Thrown by the SWC HTML minifier wrapper in @docusaurus/bundler when @swc/html fails to minify a page's HTML during build with Docusaurus Faster enabled (getSwcMinifier). The original SWC error is attached as `cause`. This is the faster/SWC counterpart of the Terser minifier error.

Source

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

          removeRedundantAttributes: 'none',

          minifyJs: true,
          minifyJson: true,
          minifyCss: true,
        });

        const warnings = (result.errors ?? []).map((diagnostic) => {
          return `[HTML minifier diagnostic - ${diagnostic.level}] ${
            diagnostic.message
          } - ${JSON.stringify(diagnostic.span)}`;
        });

        return {
          code: result.code,
          warnings,
        };
      } catch (err) {
        throw new Error(`HTML minification failed (SWC)`, {
          cause: err,
        });
      }
    },
  };
}

View on GitHub (pinned to 3f483e80e3)

Solutions

1. Inspect err.cause for the SWC diagnostic (byte span + message) and fix the offending HTML.
2. Temporarily set SKIP_HTML_MINIFICATION=true to unblock the build and confirm the minifier is the culprit.
3. Align @docusaurus/faster and @swc/core versions with the ones Docusaurus recommends for your version.
4. Fall back to the Terser minifier by disabling future.faster htmlMinifier if SWC is incompatible with your markup.

Example fix

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

// no inline pre-check; isolate with:
// process.env.SKIP_HTML_MINIFICATION = 'true'

When it happens

Trigger: Building with future.faster enabled and the SWC HTML minifier selected, when @swc/html cannot process the rendered HTML of a route. Reached via importSwcHtmlMinifier -> faster.getSwcHtmlMinifier -> swcHtmlMinifier(Buffer).

Common situations: Malformed HTML from a custom theme component; an inline <script>/<style> block SWC cannot re-minify; an @docusaurus/faster or @swc/core version mismatch after an upgrade.

Related errors

• HTML minification failed (Terser)
• You can't use siteConfig.webpack.jsLoader and siteConfig.fut
• To enable Docusaurus Faster options, your site must add the
• MDX compilation failed for file ${logger.path(filePath)} Cau
• Copying Docusaurus template name=${source.template.name} fai

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