Vite "Pre-transform error" - Fix Plugin/Transform Failures in CI

By Kaveh Alemi·Latchkey

Vite pre-transforms modules ahead of time, and one of those transforms threw. The wrapper says "Pre-transform error"; the real cause - a syntax error, a missing plugin, or a transform that does not match the file type - is in the lines beneath it.

What this error means

Vite logs Pre-transform error: followed by a specific failure (a parse error, a plugin throwing, an esbuild transform error). The build or dev server reports the module and the underlying error.

Pre-transform error: Transform failed with 1 error:
/app/src/components/Card.tsx:14:2: ERROR: Expected ">" but found "className"
  Plugin: vite:esbuild
  File: /app/src/components/Card.tsx

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

Syntax esbuild cannot parse

Vite's esbuild transform expects the file to match its loader. JSX in a .ts file (instead of .tsx), or a real syntax error, makes the transform throw.

A plugin transform misconfigured or failing

A Vite/Rollup plugin in the transform chain (e.g. a SVGR, MDX, or framework plugin) errors on a file it was not configured to handle, or is incompatible with the installed Vite version.

How to fix it

Fix the underlying syntax/loader

1. Read the error beneath "Pre-transform error" - it names the file, line, and real cause.
2. Put JSX in .tsx/.jsx files so esbuild uses the JSX loader.
3. Correct the actual syntax error the transform reports.

Align plugins with the Vite version

Ensure each plugin supports your Vite major and is ordered/configured correctly.

npm ls vite
# upgrade a stale plugin to its Vite-compatible release
npm install @vitejs/plugin-react@latest

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

• Use .tsx/.jsx extensions for files containing JSX.
• Keep Vite and its plugins on compatible versions.
• Run vite build in CI so transform errors surface before deploy.

Frequently asked questions

Related guides

References

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