Cypress "Webpack Compilation Error" - Spec Bundling Failures

By Kaveh Alemi·Latchkey

Cypress bundles each spec (and the support file) with its preprocessor before running it. A "Webpack Compilation Error" means that bundle step failed - a missing module, an unhandled file type, or a TypeScript/syntax error in the spec.

What this error means

A spec fails to start with "Webpack Compilation Error" and a module-not-found or loader error. The app itself builds fine; the failure is in compiling the test code, not the application.

Cypress output

Webpack Compilation Error
Module not found: Error: Can't resolve '../support/commands' in
'/app/cypress/e2e'

  @ ./cypress/e2e/login.cy.ts 3:0-39

Diagnose it: browser, server, or timing?

End-to-end failures in CI are dominated by three causes that have nothing to do with the test: the browser binary is missing, the application under test is not listening yet, or the test raced the page. Establish which before reading the assertion.

Terminal

# 1. are the browsers actually installed in THIS job?
npx playwright install --with-deps chromium
npx playwright --version

# 2. is the app up before the tests start?
npx wait-on http://localhost:3000 --timeout 60000

# 3. capture evidence for the failure you cannot reproduce
npx playwright test --trace on --video retain-on-failure

Common causes

Bad import path in a spec or support file

A spec imports a helper or command file that does not exist at that path (often a case mismatch on Linux), so the bundler cannot resolve it.

Missing loader or TS config for spec syntax

TypeScript or non-JS imports in specs need the preprocessor configured. Without it, the bundle hits syntax it cannot compile.

How to fix it

Fix the import and align the preprocessor

Correct the failing import path, matching filename case exactly.
Ensure cypress/tsconfig.json (or the preprocessor) handles the spec’s TypeScript/JSX.
Confirm supportFile points at the real support module.

Use the bundled preprocessor config

cypress.config.ts

// cypress.config.ts
import { defineConfig } from 'cypress';
export default defineConfig({
  e2e: { supportFile: 'cypress/support/e2e.ts', specPattern: 'cypress/e2e/**/*.cy.ts' },
});

Make the browser cache safe

Key the browser cache to the exact test-runner version. A cache restored from a different version gives you a binary that does not match the client and fails in a way that reads like a missing install.
Install browsers after dependencies, not before; a dependency install can replace the package that owns the browser path.
Prefer the vendor container image when the runner allows it. It removes the whole class of missing-system-library failures.

How to prevent it

Keep import paths and filename case consistent (Linux is case-sensitive).
Configure a cypress/tsconfig.json for TypeScript specs.
Lint specs so unresolved imports are caught before CI.

Frequently asked questions

What causes Cypress "Webpack compilation Error"?

There are 2 common causes: bad import path in a spec or support file and missing loader or ts config for spec syntax. A spec imports a helper or command file that does not exist at that path (often a case mismatch on Linux), so the bundler cannot resolve it.

How do I fix Cypress "Webpack compilation Error"?

There are 2 fixes depending on which cause you have: fix the import and align the preprocessor and use the bundled preprocessor config. Work through them in order, since the first is the most common.

What does Cypress "Webpack compilation Error" actually mean?

A spec fails to start with "Webpack Compilation Error" and a module-not-found or loader error.

How do I stop Cypress "Webpack compilation Error" happening again?

Keep import paths and filename case consistent (Linux is case-sensitive). The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation