Skip to content
Tutorials Center
My learning

Topics

Lesson 38 of 38 ยท Projects and Practice

Troubleshooting and Practice

Fix common webpack errors fast: module not found, loader and export errors, HMR and cache problems, slow builds and oversized bundles, plus practice exercises and interview questions.

Every webpack user meets the same handful of errors. Once you can read the messages and know the usual causes, most problems take minutes instead of hours. This final lesson collects the common errors with their fixes, a method for debugging slow or bloated builds, and practice exercises and review questions that cover the whole course.

Webpack is not runnable on this site, so commands and configs are read-only. The TryIt blocks are Node.js stand-ins: an error-message explainer that matches typical messages to causes, and a small checker for the exercise on aliases. They are study tools, not webpack features.

A debugging method

  1. Read the first error, not the last. One broken import often causes a screen of follow-ups.
  2. Find the file and loader. The message names the module and, for loader errors, which loader failed.
  3. Reproduce with the smallest config. Comment out plugins and rules until the problem disappears.
  4. Look at the actual output. Build with devtool: false and optimization.minimize: false and read dist/.
  5. Ask webpack. webpack --stats verbose, --profile, and stats.json explain why a module was included.

Useful commands:

Terminal
npx webpack --mode development --devtool false       # readable output
npx webpack --stats-reasons --stats-modules-space 50  # why each module is in
npx webpack --json=stats.json && npx webpack-bundle-analyzer stats.json
npx webpack configtest                                 # validate the config (CLI)
node --trace-deprecation node_modules/webpack/bin/webpack.js

Common errors

Message Usual cause Fix
Module not found: Can't resolve './x' Wrong path, missing extension, or case mismatch (works on Windows, fails on Linux CI) Fix the path; add resolve.extensions; match case exactly
Can't resolve 'crypto' / 'path' / 'fs' Node built-in in browser code (webpack 5 has no polyfills) Use a browser API, add resolve.fallback, or fs: false
You may need an appropriate loader to handle this file type No rule matches (JSX, CSS, TS, images) Add the right rule and loader, check test and exclude
Unexpected token in a dependency A package ships modern syntax your rule excludes Include that package in the Babel rule (include), or target an older output
Module parse failed ... .css Missing css-loader and style-loader Add both, in the right order
export 'x' was not found in './y' Importing a name the module does not export, or a CommonJS/ESM mismatch Fix the name; check default versus named exports
Shared module is not available for eager consumption Module Federation without an async boundary Move start-up code to import('./bootstrap')
ChunkLoadError: Loading chunk N failed Stale chunk after deploy, network failure, or wrong publicPath Keep old files, set publicPath, retry and reload
Uncaught ReferenceError: process is not defined Webpack 5 does not define process Use DefinePlugin for the specific value, or ProvidePlugin
Invalid configuration object Typo or old option name Read the message; it lists the valid keys (see the 4 to 5 guide)
Conflict: Multiple assets emit different content to the same filename Two chunks with the same output name Use [name] or [contenthash] in file names
JavaScript heap out of memory Huge build, source maps, no cache Raise NODE_OPTIONS=--max-old-space-size=4096, split work, enable filesystem cache

An explainer stand-in

This stand-in matches an error message to a known pattern and prints the likely cause. Teams sometimes build the same kind of helper into their npm run build wrapper.

Node.js Stand-in: explain a webpack error

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Slow builds

  • Turn on the filesystem cache (cache: { type: 'filesystem' }) and babel-loader's cacheDirectory.
  • Narrow loader scope with include and exclude; never run Babel over all of node_modules unless needed.
  • Use a faster transpiler: swc-loader or esbuild-loader, with type checking in a separate process.
  • Use a cheaper devtool in development (eval-cheap-module-source-map).
  • Profile: --profile --json plus the speed-measure-webpack-plugin or Chrome's --inspect to find slow loaders.
  • Consider Rspack or another bundler if the architecture is the limit (see alternatives).

Oversized bundles

Follow the analysis routine: sort by package, find duplicates, check tree shaking, make heavy code lazy, and cut polyfills.

Hot reload not working

  • The page does a full reload instead of a hot update: the changed module has no HMR handler, or the update bubbles up to the entry. Fast Refresh and framework loaders add the handlers.
  • Nothing updates: check devServer.hot, that output.publicPath matches, and that a proxy or firewall is not blocking WebSocket connections.
  • Changes only on restart: files outside the watched directory, or watchOptions.ignored too broad.

Practice exercises

Try them first, then compare with the hints.

  1. Aliases. Make import { api } from '@/services/api' work in both webpack and your editor. Hint: resolve.alias and a matching paths entry in tsconfig.json.
  2. Stable hashes. After adding a small new utility file, your vendor chunk hash changes. Find three possible causes. Hint: ids, runtime chunk, vendor in the app chunk.
  3. Heavy library. Your analyzer shows a 180 KB chart library on the home page, which does not draw charts. Move it off the critical path. Hint: import() in the route that draws charts, plus prefetch.
  4. CSS flash. Production shows unstyled content for a moment. Check how CSS is delivered. Hint: style-loader injects after JS runs; extract to files with MiniCssExtractPlugin.
  5. Library build. You publish a UI library. List the settings you would use. Hint: externals for React, output.library, ES module output or Rollup instead.
  6. Dead code. import { debounce } from 'lodash' adds 70 KB. Reduce it. Hint: lodash-es or lodash/debounce, check sideEffects.

The stand-in below turns exercise 1 into a tiny checker: given aliases from the two configs, it reports which ones disagree, which is exactly the bug that makes the editor happy and the build fail.

Node.js Stand-in: do webpack and tsconfig aliases agree?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Review questions

Use these to test yourself or to prepare for interviews.

  • What is the difference between a module, a chunk and a bundle?
  • What do loaders do compared with plugins?
  • Why do loaders in a use array run right to left?
  • What is the purpose of contenthash, and what can make it change unexpectedly?
  • Name two ways to create a chunk, and when you would use each.
  • How does tree shaking work, and why does CommonJS defeat it?
  • Why do production builds replace process.env.NODE_ENV?
  • What changed with Node polyfills between webpack 4 and 5?
  • What problem does Module Federation solve, and what does it cost?
  • When would you pick Vite or Rspack over webpack?

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A build works on your Windows laptop but fails on Linux CI with 'Can't resolve ./Button'. What is a likely cause?

    Windows file systems are usually case-insensitive and Linux ones are not, so a case mismatch only fails on Linux.
  2. 2. 'You may need an appropriate loader to handle this file type' means:

    Webpack only understands JavaScript and JSON by default. Other file types need rules with loaders or asset modules.
  3. 3. Which is the best first step when a build is slow?

    Caching and profiling give big gains with little risk, and show where the real cost is.
  4. 4. Hot reload keeps doing full page reloads. Which is a typical reason?

    If no module accepts the update, webpack falls back to reloading the page. Framework loaders normally add the handlers.
  5. 5. Which pair of settings keep editor and build alias resolution in sync?

    The type checker reads tsconfig paths while webpack reads resolve.alias; they must describe the same mapping.

Summary

  • Read the first error, find the module and loader, and shrink the problem.
  • Most errors are path, loader, polyfill or export mismatches; each has a standard fix.
  • Speed up builds with caching, scoped loaders and faster transpilers; shrink bundles with analysis.
  • Practise by explaining your own config line by line.

You have reached the end of this part of the course. Return to the Webpack tutorial home to review earlier chapters.

Next: Webpack