Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

html-webpack-plugin stops the build with 'Child compilation failed'

ErrorError: Child compilation failed

Short answer

html-webpack-plugin compiles your HTML template in a child webpack compilation that inherits your loader rules. 'Child compilation failed' only wraps the real error below it. Read that line first. Usually a rule such as html-loader grabs the .html template, or the template uses template syntax the default loader cannot parse.

  • Applies to html-webpack-plugin 5, webpack 5, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Scroll below the words 'Child compilation failed'. The lines that follow come from the template's own loader and name the real problem. Run a plain build so the output is not hidden.

    npx webpack --mode development
  2. 2Match what you see, then jump to its fix

    1. 1The lines under the error mention html-loader, a different loader, or an unexpected token inside <%= %>.Another module.rules entry also matches the template fileFix
    2. 2A syntax or reference error from the lodash template, pointing at a line with <% %> in the template.The template uses ejs syntax the fallback loader does not supportFix

What does the error look like?

  • Error: Child compilation failed
  • Child compilation failed: followed by an error from the template's loader

Cause 1 of 2

Another module.rules entry also matches the template file

1Check

The plugin builds the template in a child compilation that inherits all the loaders from your main config. A rule with test /\.html$/ will therefore process your template, which can minify it and replaces the default template loader.

grep -n -B2 -A4 "html" webpack.config.js

2Fix

Name the loader you want right in the template option, with the !! prefix, so that no other rule applies. The docs show this form for handlebars-loader; the same prefix works for whichever loader you need.

new HtmlWebpackPlugin({
  // !! skips the normal rules for this one file
  template: '!!handlebars-loader!src/index.hbs',
});

3Verify

Run the build again. The template compiles and dist/index.html is written.

npx webpack --mode production

Confirmed by github.com

Did this fix it?

Cause 2 of 2

The template uses ejs syntax the fallback loader does not support

1Check

With no loader set, the plugin falls back to a loader based on lodash templates. The docs warn that it does not support the full ejs syntax. Check which tags the template uses.

grep -n "<%" src/index.html

2Fix

Limit the template to lodash-style tags such as <%= htmlWebpackPlugin.options.title %>, or set a template loader that does support your syntax (see the docs for the template option).

<title><%= htmlWebpackPlugin.options.title %></title>

3Verify

Rebuild. The child compilation finishes and the title appears in the generated HTML.

grep -n "<title>" dist/index.html

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep one loader strategy for templates: either the default, or one named loader in the template option.
  • After adding an html-loader rule for other files, rebuild once and read the html-webpack-plugin output.
  • Pin html-webpack-plugin to the major version your webpack config was written for.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

tsconfig rejects allowImportingTsExtensions

An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly

allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.