webpack — Module parse failed: Unexpected token

Fix webpack parse failures by adding the right loader for the file type and excluding build artifacts from rule matching.

intermediatedebuggingnodewebpack

Symptoms

Module parse failed: Unexpected token (12:8)
You may need an appropriate loader to handle this file type
The error appears after adding a new file extension
A dependency needs transpilation but is not matched

Possible causes

No loader is configured for the file type being imported
A rule excludes node_modules so an ESM dependency is not transpiled
A rule matches files it should not, such as already-built output
The file contains syntax newer than the configured target

Diagnosis steps

Identify the file type in the error

npx webpack --stats detailed

Interpretation

The message names the source file and token, showing which extension and syntax the loader set does not cover.

Add a rule for the extension

module: { rules: [{ test: /\.tsx?$/, use: 'ts-loader' }] }

Interpretation

A matching rule with the appropriate loader lets webpack parse and transform the file.

Include the offending dependency

rules: [{ test: /\.m?js$/, include: /node_modules\/some-esm-dep/, use: 'babel-loader' }]

Interpretation

ESM-only dependencies excluded from all rules need an explicit include so they get transpiled.

Root cause

webpack could not parse the file because no configured rule and loader matches its type or location, so it handed the raw source to a parser that does not understand the syntax.

Fix

Add or correct loader rules for each imported file type and include dependencies that need transpilation, while restricting rules so they do not process unrelated or already-built files.

Verify the fix

Rebuild and confirm the parse error is gone, and confirm the resulting bundle runs the code that previously failed to parse.

Symptom walkthrough

Building fails with Module parse failed: Unexpected token and a note that an appropriate loader may be needed. webpack encountered syntax it cannot parse because no rule matched that file type or location. A frequent variation is an ESM dependency under node_modules that a rule excludes from transpilation, leaving modern syntax for the parser to choke on.

Fix in practice

Add a loader rule covering the file extension, and include any dependency that ships untranspiled modern syntax. Keep rules tight so they do not accidentally process already-built output or unrelated files, which can cause confusing secondary errors.

Verification

Rebuild and confirm the parse error is gone, then run the built bundle and exercise the code path that previously failed. A successful build that also runs correctly confirms the loader configuration. Adding a test build in CI catches loader regressions long before they reach deployment.

Diagnostic commands

Check the behavior with commands like these:

npx webpack --stats detailed
module: { rules: [{ test: /\.tsx?$/, use: 'ts-loader' }] }
rules: [{ test: /\.m?js$/, include: /node_modules\/some-esm-dep/, use: 'babel-loader' }]