html-webpack-plugin stops the build with 'Child compilation failed'
Error: Child compilation failedShort 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.
Fix it fast
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 development2Match what you see, then jump to its fix
- 1
The 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
A 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
- 1
What does the error look like?
Error: Child compilation failedChild 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.js2Fix
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 productionConfirmed by github.com
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.html2Fix
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.htmlConfirmed by github.com
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 fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix