Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallSome links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To see Webpack bundle diagnostics from Cypress’s @cypress/webpack-preprocessor, run Cypress with DEBUG=cypress:webpack:stats. For broader preprocessor messages, use DEBUG=cypress:webpack; add cypress:server:preprocessor to trace Cypress’s preprocessing layer. These settings expose different kinds of information: stats cover items such as timings, chunks, and sizes, while source maps help errors point back to your original source code.
First confirm that the failure is actually in Cypress’s test-file preprocessing. An application build that runs separately, a custom preprocessor, or a component-testing dev server may need diagnostics from a different process or bundler.
Enable Webpack and Cypress preprocessor debug output
For the default end-to-end (E2E) preprocessing path using @cypress/webpack-preprocessor, set the DEBUG environment variable before starting Cypress:
DEBUG=cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats npx cypress runThe comma-separated names enable three scopes of messages together. Cypress’s troubleshooting documentation describes comma-separated debug namespaces; the preprocessor package documents the Webpack-specific namespaces.
#1 Best Overall
cypress:webpack:statsis the targeted option for Webpack bundle diagnostics, including timings, chunks, and sizes.cypress:webpackenables broader messages from the Webpack preprocessor.cypress:server:preprocessorhelps show Cypress’s preprocessor lifecycle.
Use the stats namespace when you need bundle-level detail; add the other namespaces when you need context about how Cypress hands a test file to the preprocessor. More debug output does not itself fix a compilation problem, and stats are not a replacement for the compiler’s first actionable error.
Run from a POSIX-style shell
The command above works in shells that support setting an environment variable inline, such as common macOS and Linux shells. It starts Cypress in run mode. To diagnose a failure in a different invocation, set the same variable before that invocation instead.
Set the variable in other environments
In Windows Command Prompt, set the variable for the current command session, then run Cypress:
set DEBUG=cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats
npx cypress runIn PowerShell, use:
$env:DEBUG = "cypress:server:preprocessor,cypress:webpack,cypress:webpack:stats"
npx cypress runThese examples set a process environment variable; they do not change Cypress configuration files. If Cypress is started by an IDE, package script, or CI job, make sure the variable reaches that process. Otherwise, Cypress may run without the requested logs even though the command works in a separate terminal.
Read the failure in the right order
Cypress’s “We found an error preparing your test file” message means Cypress could not compile or bundle that test file. Cypress lists a missing file, a syntax error in the file or one of its dependencies, and a missing dependency among common causes.
- Find the first meaningful error. Read the compiler or bundler error before interpreting later messages. A later failure may simply follow from the first unresolved module or syntax problem.
- Identify the file or module named. Check whether that path is correct and the file exists. If the error points into an imported dependency, inspect that module too rather than assuming the spec itself is at fault.
- Check the dependency. If the message names an unavailable package, confirm that it is installed in the project context where Cypress runs and that the import uses the intended package name.
- Use stats for bundle context. Timings, chunks, and sizes can help characterize what Webpack processed, but they do not replace the specific missing-file, syntax, or dependency error that identifies a likely fix.
- Verify which process owns the error. A test-file preparation message points toward preprocessing. A separately invoked application build should be run with that build tool’s own diagnostic options.
Confirm the active Cypress compilation path
The Webpack debug namespaces are useful only when the failing file is going through the corresponding Webpack preprocessor. Cypress documents a default preprocessor for spec and support files when a custom file:preprocessor is not supplied. The package includes a default setup for TypeScript and JSX support. A project can also register a custom preprocessor, and component testing has a distinct dev-server path.
E2E spec or support-file preprocessing
For the default E2E path, the package-specific cypress:webpack and cypress:webpack:stats settings are the relevant Webpack diagnostics. If the project registers its own file:preprocessor, verify which implementation is active and whether it uses Webpack before expecting these namespaces to show useful output.
Component testing
Cypress’s component-testing documentation distinguishes its dev server from default E2E spec preprocessing. Component-test module aliases are resolved through the configured Vite or Webpack dev-server configuration. If the compilation error occurs there, investigate that dev server’s configuration and logs rather than assuming the default E2E preprocessor is responsible.
Application builds run outside Cypress
If a test launches or depends on an application build that fails independently, the Cypress preprocessor’s debug output will not necessarily explain that build. Run the application’s own build command and use its compiler or bundler diagnostics. Keep the two failure paths separate: Cypress must prepare its test and support files, while the application build prepares the application.
Configure Webpack aliases when imports cannot resolve
The default Webpack preprocessor does not automatically take path aliases from compilerOptions.paths in tsconfig.json or from _moduleAliases in package.json. An import that works in another part of the project can therefore fail while Cypress preprocesses an E2E file.
Configure the alias in Webpack’s resolve.alias, or, where appropriate, configure a tsconfig-paths-webpack-plugin. The important diagnostic distinction is between an alias that your application tooling understands and one the preprocessor’s Webpack configuration actually knows about. Check the exact unresolved import in the error, then make the resolution rule available to the active preprocessor.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsDo not apply this E2E alias advice blindly to component tests: Cypress documents that component-test aliases are handled by the dev server’s Vite or Webpack configuration.
Rank #4
Use source maps for readable error locations
Webpack stats and source maps solve different problems. The stats namespace reports bundle diagnostics; source maps help Cypress show source files and code frames for errors. For Webpack used with the Cypress Webpack preprocessor, Cypress documents devtool: 'inline-source-map'. Without inline source maps, Cypress says code frames will not appear.
When errors point into generated bundle output or lack a helpful code frame, check the Webpack devtool setting in the configuration actually used by the preprocessor. Inline source maps improve source-level locations; they do not enable or expand the compilation statistics stream.
Customize the preprocessor when project options are needed
If the default settings are insufficient, Cypress’s preprocessor API allows registering @cypress/webpack-preprocessor through on('file:preprocessor', ...) in setupNodeEvents and passing Webpack configuration to the preprocessor. This is the point to provide project-specific options such as aliases. Confirm that the registered preprocessor is the one receiving the failing spec, then rerun with the relevant debug namespaces.
Recommended Free Tools
Avoid changing several layers at once. First establish whether the failure is in E2E preprocessing, component-test dev-server compilation, or an external application build. Then modify the configuration owned by that layer and compare the next error with the original first failure.
Best Value
Troubleshooting common cases
| Symptom | Likely explanation | What to check |
|---|---|---|
| No Webpack stats appear | The relevant process may not receive DEBUG, or the failing path may not use @cypress/webpack-preprocessor. |
Set the variable in the shell or launcher that starts Cypress. Confirm that the error belongs to E2E preprocessing and that a custom preprocessor has not replaced the default. |
| Cypress says it could not prepare a test file | A missing file, syntax error, or missing dependency is among Cypress’s documented common causes. | Start with the first compilation error and the named file or module. Check the path, syntax, and project dependency installation. |
| An import works elsewhere but fails in an E2E spec | The default Webpack preprocessor may not know an alias defined only in TypeScript or package configuration. | Add the alias to Webpack’s resolve.alias or use an appropriate tsconfig-paths-webpack-plugin configuration. |
| A component-test alias still fails after changing E2E Webpack configuration | Component tests resolve aliases through their dev server, which may have a separate Vite or Webpack configuration. | Change the active component dev-server configuration and inspect its compilation diagnostics. |
| The error lacks a useful source code frame | Source maps may not be configured for the Webpack preprocessor. | Use the documented devtool: 'inline-source-map' setting in the Webpack configuration used for that preprocessing path. |
| Webpack diagnostics do not explain an application build failure | The failing build may run outside Cypress’s test-file preprocessor. | Run the application build separately and use its own build-tool logs. |
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server, not a Cypress Webpack diagnostic tool. It will not reveal why a test file failed to compile. If your separate task is to capture a website page without setting up browser automation, a single API request returns an image or PDF. The API accepts parameters used by other screenshot APIs, which can make switching easier. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify page verdict and billing status in headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Do Webpack stats show the original source line for an error?
Not by themselves. Cypress’s documented inline source-map setting is what enables source-level code frames; stats and source maps serve separate purposes.
Will these DEBUG settings diagnose every Cypress bundler?
No. The Webpack-specific settings apply to the Webpack preprocessor path; custom preprocessors and component-test dev servers can use different compilation paths.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
