Troubleshooting

Using webpack can lead to a variety of runtime warnings or errors. Often a particular part of the build fails for a reason or another. A basic process can be used to figure out these problems:

1. Enable stats.errorDetails in webpack configuration to get more information.
2. Study the origin of the error carefully. Sometimes you can infer what's wrong with context. If webpack fails to parse a module, it's likely not passing it through a loader you expect for example.
3. Try to understand where the error stems. Does it come from your code, a dependency, or webpack?
4. Remove code until the error goes away and add code back till it appears again. Simplify as much as possible to isolate the problem.
5. If the code worked in another project, figure out what's different. It's possible the dependencies between the projects vary, or the setup differs somehow. At the worst case, a package you rely upon has gained a regression. Using a lockfile is a good idea for this reason.
6. Study the related packages carefully. Looking into the package package.json can yield insight. It's possible the package you are using does not resolve the way you expect.
7. Search for the error online. Perhaps someone else has run into it. Stack Overflow and the official issue tracker are good starting points.
8. Enable stats: "verbose" to get more information out of webpack. The official documentation covers more flags.
9. Add a temporary console.log near the error to get more insight into the problem. A heavier option is to debug webpack through Chrome Dev Tools.
10. Ask a question at Stack Overflow or use the official Gitter channel.
11. If everything fails and you are convinced you have found a bug, report the problem at the issue tracker that's closest to it. Follow the issue template carefully, and provide a minimal runnable example as that will help the maintainers.

Sometimes it's fastest to drop the error to a search engine and gain an answer that way. Other than that this is an excellent debugging order. If your setup worked in the past, you could also consider using commands like git bisect to figure out what has changed between the known working state and the current broken one.

You'll learn about the most common errors next and how to deal with them.

Module related errors#

Webpack emits various module related errors. I've listed the main ones and how to resolve them here.

Entry module not found#

You can get ERROR in Entry module not found if you make an entry path point at a place that does not exist. The error message tells you what path webpack fails to find.

Module not found#

You can receive ERROR ... Module not found in two ways. Either by breaking a loader definition so that it points to a loader that does not exist or by breaking an import path within your code so that it leads to a module that doesn't exist. The message points out what to fix.

Module parse failed#

Even though webpack could resolve to your modules fine, it can still fail to build them and that's when you likely receive a Module parse failed error. This case can happen if you are using syntax that your loaders don't understand. You could be missing something in your processing pass.

Loader not found#

There's another subtle loader related error, Loader Not Found. If a package matching to a loader name that does not implement the loader interface exists, webpack matches to that and gives a runtime error that says the package is not a loader.

If you write loader: "eslint" instead of loader: "eslint-loader", you'll receive this error. If the package doesn't exist at all, then Module not found error will be raised.

Module build failed: Unknown word#

Module build failed: Unknown word fits the same category. Parsing the file succeeded, but there was the unknown syntax. Most likely the problem is a typo, but this error can also occur when Webpack has followed an import and encountered syntax it doesn't understand. Most likely this means that a loader is missing for that particular file type.

SyntaxError: Unexpected token#

SyntaxError is another error for the same category. This error is possible if you use ES2015 syntax that hasn't been transpiled alongside terser. As it encounters a syntax construct it does not recognize, it raises an error.

DeprecationWarning#

Node may give a DeprecationWarning especially after webpack has been updated to a new major version. A plugin or a loader you are using may require updates. Often the changes required are minimal. To figure out where the warning is coming from, run webpack through Node: node --trace-deprecation node_modules/.bin/wp --mode production.

It's important to pass the --trace-deprecation flag to Node to see where the warning originates from. Using --trace-warnings is another way and it will capture the tracing information for all warnings, not only deprecations.

Conclusion#

These are only examples of errors. Specific errors happen on the webpack side, but the rest comes from the packages it uses through loaders and plugins. Simplifying your project is a good step as that makes it easier to understand where the error happens.

In most cases, the errors are fast to solve if you know where to look, but in the worst case, you have come upon a bug to fix in the tooling. In that case, you should provide a high-quality report to the project and help to resolve it.