webpack "Module parse failed: Unexpected token" - Need a Loader

By Kaveh Alemi·Latchkey

webpack only understands plain JavaScript on its own. When it meets JSX, TypeScript, modern syntax, or a non-JS file with no matching loader, it cannot parse it and stops with "Unexpected token".

What this error means

The build fails with Module parse failed: Unexpected token and the tell-tale line "You may need an appropriate loader to handle this file type." It points at JSX, TS, or a CSS/asset import that no rule covers.

ERROR in ./src/Button.jsx 5:9
Module parse failed: Unexpected token (5:9)
You may need an appropriate loader to handle this file type, currently
no loaders are configured to process this file.
>   return <button>Click</button>;

Diagnose it: is it resolution, transform, or memory?

Bundler failures in CI fall into three families and the error text often points at the wrong one. A module that resolves on your machine and not on the runner is nearly always case sensitivity or a missing optional dependency; a transform error is a config or version mismatch; and an unexplained kill with no stack is the out-of-memory reaper, not a build error at all.

# 1. resolution: does the file exist with EXACTLY that case?
git ls-files | grep -i "the/imported/path"

# 2. transform: what versions is CI actually resolving?
npm ls webpack vite rollup esbuild typescript 2>/dev/null | head -20

# 3. memory: was it killed rather than failed?
#    exit 137 = SIGKILL (OOM). Nothing in the bundler log will explain it.
node --max-old-space-size=4096 node_modules/.bin/vite build

Common causes

No loader for JSX/TS syntax

JSX or TypeScript needs babel-loader, ts-loader, swc-loader, or esbuild-loader. Without a rule matching the file, webpack parses it as plain JS and chokes on < or a type annotation.

A loader excludes the file

A rule exists but its include/exclude skips the file - commonly exclude: /node_modules/ when a dependency ships untranspiled ESNext that needs transpiling.

Non-JS asset imported without a rule

Importing .css, .svg, or similar with no css-loader/asset-module rule makes webpack parse the file contents as JavaScript.

How to fix it

Add a loader rule for the syntax

Configure a transpiler for JSX/TS files and rules for assets.

// webpack.config.js
module: {
  rules: [
    { test: /\.[jt]sx?$/, exclude: /node_modules/, use: 'babel-loader' },
    { test: /\.css$/, use: ['style-loader', 'css-loader'] },
  ],
}

Stop excluding a dependency that needs transpiling

When a node_modules package ships untranspiled code, narrow the exclude so it is processed.

{ test: /\.m?js$/, include: /node_modules\/some-esnext-pkg/, use: 'babel-loader' }

Make the build reproducible before you debug it

• Pin the Node major in setup-node and in engines. A bundler that resolves native bindings will pick a different prebuilt binary across majors.
• Delete node_modules locally and reinstall from the lockfile before concluding the runner is at fault; most "works locally" reports are stale local state.
• Set CI=true locally to reproduce. Several toolchains change behaviour under it, including treating warnings as errors.
• Exit code 137 is an out-of-memory kill. Raise --max-old-space-size or move to a larger runner rather than searching the bundler config.

How to prevent it

• Define loader rules for every file type you import (JS/TS/JSX, CSS, assets).
• Be deliberate about exclude: /node_modules/ - some deps ship untranspiled.
• Keep your Babel/TS preset list aligned with the syntax features you use.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation