ScreenshotNeo

BlogHow-to

How to Get Detailed Webpack Compilation Errors in Cypress

Use Cypress debug namespaces, Webpack stats, source maps, and alias checks to turn vague test preparation failures into actionable errors.

By the ScreenshotNeo team30 September 20267 min read

How to Get Detailed Webpack Compilation Errors in Cypress

When Cypress says it found an error preparing your test file, enable the debug namespaces used by the active preprocessor. For the @cypress/webpack-preprocessor package, the most targeted command is:

DEBUG=cypress:webpack:stats npx cypress run

Use DEBUG=cypress:webpack for broader preprocessor messages. To trace Cypress’s preprocessing lifecycle as well, combine namespaces:

DEBUG=cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats npx cypress run

The output can include compilation timings, chunks, and asset sizes, plus messages about files being processed. The exact output depends on which preprocessor and test mode produced the failure. These settings apply to the Webpack preprocessor; a component test using a Vite or Webpack dev server, or an application build run in a separate process, may use different diagnostics.

What the debug namespaces show

Namespace Scope Useful for
cypress:webpack:stats Webpack compilation statistics Timings, chunks, module and asset size information
cypress:webpack Webpack preprocessor messages Which files are processed and broader bundling diagnostics
cypress:server:preprocessor Cypress preprocessing lifecycle Tracing handoff between Cypress and the configured file preprocessor

The DEBUG variable does not fix a syntax error, install a missing dependency, or configure an alias. It exposes more context so you can locate the first real error. Cypress supports comma-separated namespaces in its troubleshooting documentation. See the webpack preprocessor README and Cypress troubleshooting guide.

Step 1: Confirm which build is failing

Before changing Webpack settings, classify the failure. Cypress can compile several different things:

Separate Cypress lifecycle logs, Webpack stats, and source maps to locate the real failure.
Separate Cypress lifecycle logs, Webpack stats, and source maps to locate the real failure.
  • End-to-end spec or support file: the default Webpack preprocessor bundles the file before the browser runs it.
  • Component test: the configured dev server, using Vite or Webpack, compiles the component and support code.
  • Application build: your own webpack, Vite, Next.js, or other command may build the application independently of Cypress.

The familiar “We found an error preparing your test file” message normally refers to the first case. Cypress lists a missing file, a syntax error in the spec or one of its dependencies, and a missing dependency among common causes. If the stack trace points to an application build command, run that command with its own logging options instead.

Step 2: Run Cypress with progressively broader logs

Start with the narrow setting when you want bundle statistics:

DEBUG=cypress:webpack:stats npx cypress run --spec cypress/e2e/login.cy.ts

Add the general Webpack namespace when the statistics do not explain which module was being processed:

DEBUG=cypress:webpack,cypress:webpack:stats npx cypress run --spec cypress/e2e/login.cy.ts

Add the Cypress server namespace to observe preprocessing events:

DEBUG=cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats npx cypress open

On Windows PowerShell, set the variable for the command’s process:

$env:DEBUG="cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats"
npx cypress run

On Windows Command Prompt:

set DEBUG=cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats && npx cypress run

Keep the command focused on one failing spec while investigating. Redirect output to a file if a CI log is too large:

DEBUG=cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats npx cypress run > cypress-webpack.log 2>&1

Step 3: Read the first meaningful compilation error

Webpack can emit secondary errors after the original failure. Work from the first error that names a file or module:

  1. Copy the path and line and column from the first error.
  2. Open that file, then inspect the import immediately above the reported location.
  3. Check whether the named module exists in the repository or in node_modules.
  4. Read the “caused by” section. A syntax error in an imported helper can appear as though the spec itself failed.
  5. Re-run only the affected spec after each correction.

A missing file often means a case mismatch that works on macOS but fails on a case-sensitive CI filesystem. A missing package usually means it was not installed in the workspace that launches Cypress, or it is listed in the wrong dependency section. A parser error can indicate that the file extension is not covered by the configured loader.

Step 4: Preserve source-level locations with inline source maps

Debug namespaces and source maps solve different problems. cypress:webpack:stats reports compilation details; source maps let Cypress show the original source file and code frame. For a custom Webpack configuration, use the documented inline setting:

Webpack aliases must be configured for the Cypress preprocessor independently of the application build.
Webpack aliases must be configured for the Cypress preprocessor independently of the application build.
const webpackPreprocessor = require('@cypress/webpack-preprocessor');

module.exports = {
  e2e: {
    setupNodeEvents(on) {
      on('file:preprocessor', webpackPreprocessor({
        webpackOptions: {
          devtool: 'inline-source-map'
        }
      }));
    }
  }
};

Without inline source maps, Cypress may show generated bundle locations without a useful code frame. Inline maps increase the size of the generated bundle, so use them for readable diagnostics and choose a production-appropriate setting for other builds. The distinction is covered in Cypress’s debugging guide.

Step 5: Configure aliases explicitly

The default Webpack preprocessor does not automatically inherit compilerOptions.paths from tsconfig.json or _moduleAliases from package.json. An import such as @/support/commands therefore fails unless Webpack knows what @ means.

Add aliases to the Webpack options passed to the preprocessor:

const path = require('path');
const webpackPreprocessor = require('@cypress/webpack-preprocessor');

module.exports = {
  e2e: {
    setupNodeEvents(on) {
      on('file:preprocessor', webpackPreprocessor({
        webpackOptions: {
          resolve: {
            extensions: ['.js', '.jsx', '.ts', '.tsx'],
            alias: {
              '@': path.resolve(__dirname, 'src'),
              '@tests': path.resolve(__dirname, 'cypress')
            }
          },
          devtool: 'inline-source-map'
        }
      }));
    }
  }
};

If you want Webpack to read TypeScript path mappings, add a compatible tsconfig-paths-webpack-plugin to the resolver instead of assuming Cypress will read the mappings itself. Component testing is different: aliases are resolved by the configured Vite or Webpack dev server. Confirm the test mode before editing setupNodeEvents. See the Cypress preprocessors API.

Step 6: Register a custom preprocessor only when needed

Cypress supplies a default Webpack preprocessor when you do not register another file:preprocessor. It includes support for common TypeScript and JSX cases. Register a custom instance when you need project-specific loaders, aliases, plugins, or source-map settings.

const webpack = require('webpack');
const webpackPreprocessor = require('@cypress/webpack-preprocessor');

module.exports = {
  e2e: {
    setupNodeEvents(on) {
      on('file:preprocessor', webpackPreprocessor({
        webpackOptions: {
          mode: 'development',
          devtool: 'inline-source-map',
          plugins: [new webpack.DefinePlugin({
            'process.env.TEST_BUILD': JSON.stringify('cypress')
          })]
        }
      }));
    }
  }
};

Do not add a second preprocessor registration without removing the old one. Multiple handlers can make it unclear which compiler produced the error.

Common errors and fixes

Error pattern Likely cause Fix
Module not found: Can't resolve Wrong path, missing package, or unconfigured alias Verify the file and casing, install the dependency in the Cypress workspace, or add resolve.alias.
Unexpected token The active loader does not parse the file syntax Check the extension and loader rules; ensure TypeScript, JSX, or the relevant syntax is configured.
Source file is missing from the code frame No inline source map Set devtool: 'inline-source-map' for the Cypress Webpack compiler.
Alias works in the app but not in Cypress Application bundler and Cypress preprocessor have separate configs Duplicate the alias in the preprocessor configuration or use a paths plugin.
Debug output is empty Wrong namespace or a different bundler is active Try all three namespaces and identify whether component testing uses Vite or another dev server.
Works locally, fails in CI Different Node version, install mode, environment variable, or filesystem casing Compare versions and lockfiles, confirm dependencies are installed, and check case-sensitive paths.
Webpack reports many errors at once One early parse or resolution failure caused cascading messages Fix the first file and line reported, then rerun the single spec.

Performance and reliability considerations

  • Scope debug runs: running one spec produces a smaller, more readable log than rebuilding the entire suite.
  • Use stats selectively: bundle-size and timing output can be verbose in CI. Enable it on failing jobs or save it as an artifact.
  • Inline maps cost build time and bytes: they improve code frames during diagnosis but should be enabled deliberately.
  • Keep configuration deterministic: pin the package lockfile, use the same Node version in local and CI environments, and avoid aliases that depend on the current working directory.
  • Separate test preprocessing from app builds: a successful Cypress bundle does not prove that the application production build succeeds.

Or skip the browser setup

If your goal is a reliable visual capture of a page after debugging, ScreenshotNeo can return an image or PDF with one request. It accepts the page URL, removes cookie banners, newsletter popups, and chat widgets before capture, and reports whether the result was clean and billable. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.

See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Every plan includes the same features, including full-page and element capture, custom CSS and JavaScript, waits, request blocking, device presets, PDFs, caching, signed links, async jobs, bulk capture, and usage reporting. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Does cypress:webpack:stats print the original source error?

It prints Webpack compilation diagnostics such as timings, chunks, and sizes. Use the compiler’s normal error output and inline source maps for source-level code frames.

Can I use these variables with Cypress Cloud?

Yes, set DEBUG in the environment that launches the Cypress process. Ensure your CI configuration passes the variable to the test command and preserves the resulting log.

Why do component tests show different messages?

Component tests use the configured dev server. If that server is Vite, Webpack namespaces will not describe its compilation. Inspect the component dev-server configuration and its logs.

Should aliases be copied into every Cypress project?

Each compiler has its own resolver. Keep a shared alias definition where practical, but verify that the E2E preprocessor and component dev server both receive it.

Will enabling debug logs change the compiled bundle?

The namespaces control logging. Source-map settings and custom Webpack options can change build output, so treat those as separate configuration changes.