Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Most Cypress Support file missing or invalid and We found an error preparing your test file failures come from one of five things: an incorrectly scoped supportFile setting, a path that does not resolve, duplicate matching files, a syntax or dependency error, or browser-incompatible code imported by cypress/support/e2e.js. First identify which file failed. The support entry file is different from cypress.config.js and plugin code, which have separate module-loading rules.
Start by identifying the failing file
Read the filename and line number in the Cypress runner or terminal output before changing code. A message naming cypress/support/e2e.js follows the support-file and browser-bundling path. Error Loading Config, a stack trace naming cypress.config.js, or a legacy plugin path requires a configuration/module-format diagnosis instead.
| Symptom or label | First checks |
|---|---|
| Support file missing or invalid | Check e2e.supportFile, the resolved path, file existence, and duplicate matches. |
| We found an error preparing your test file | Inspect the reported line, syntax, imports, package resolution, and browser compatibility. |
Error Loading Config mentioning supportFile |
Move the option under e2e (or component for component testing); root-level placement is obsolete in Cypress 10.0.0 and later. |
Cannot use import statement outside a module or a similar config parse error |
Determine whether the failing file is config/plugin code or the bundled support file, then apply the appropriate loader fix. |
The exact wording and stack trace vary by Cypress version, but the file named in the error determines which branch to follow.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated 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 matchVerify the supported e2e support-file path
Use the default entry point
For end-to-end testing, Cypress normally looks for cypress/support/e2e.js. The equivalent JSX and TypeScript names are e2e.jsx, e2e.ts, and e2e.tsx. Cypress loads this entry file before each spec, so a failure there prevents the spec from being prepared.
- From the project root, confirm that the file is physically present at
cypress/support/e2e.js(or the extension you intend to use). - Check capitalization and spelling. A path that works on a case-insensitive workstation can fail in a case-sensitive CI filesystem.
- Confirm that Cypress is being started from the project whose configuration and
cypressdirectory you inspected. - Make sure the file is not accidentally named
e2e.js.txtor placed in a component-support directory.
Configure a custom path in the correct scope
If the entry file lives elsewhere, set supportFile inside the e2e object in cypress.config.js (or the equivalent configuration file):
const { defineConfig } = require('cypress');
module.exports = defineConfig({
e2e: {
supportFile: 'cypress/support/my-e2e.js',
specPattern: 'cypress/e2e/**/*.cy.{js,jsx,ts,tsx}'
}
});For component testing, place the option under component instead. Cypress 10.0.0 moved this setting beneath the testing-type object; a root-level supportFile is not the current form. Set supportFile: false only when you deliberately want no support entry file.
Check for duplicate matches
For one testing type, the support-file setting must resolve unambiguously. Search the project for files that match the configured name or pattern. Remove, rename, or move stale copies such as an old cypress/support/e2e.js alongside a generated file that Cypress also finds. Keep one intentional entry point and import the rest from it explicitly.
Validate the file itself and every import
Reduce to a known-good entry file
Temporarily replace the support file with a minimal file to separate path problems from compilation problems:
// cypress/support/e2e.js
// Keep this file limited to browser-safe setup.
import './commands';If this loads, restore other imports one at a time until the failing module is identified. If it still fails, recheck the configured path, extension, duplicate files, and the Cypress project root.
Find syntax errors at the reported line
- Balance parentheses, braces, brackets, quotes, and template literals.
- Check that an import or export is not accidentally inside a function or conditional.
- Use syntax supported by the JavaScript/TypeScript pipeline configured for the project.
- Inspect the dependency named in the stack trace; a valid support file can still fail while its imported module is parsed.
Resolve missing packages and incorrect relative paths
Every imported package must be installed in the project that runs Cypress, and every relative path is resolved from the importing file. Verify the package name, its casing, and the extension/path of local modules. A dependency that is available only in a parent workspace, production-only install, or different package-manager environment can be absent in CI. Reinstall dependencies using the lockfile, then run Cypress from that same workspace.
Keep support code browser-compatible
Cypress bundles the support file and its imports for execution in the browser before each spec. The browser bundle is not a Node.js process. Imports such as fs, database drivers, or server-side SDKs can therefore fail even when the JavaScript syntax is valid. Move that work into Node-side configuration events and expose the operation to a test with cy.task().
Browser-side support example
// cypress/support/e2e.js
import './commands';
beforeEach(() => {
cy.intercept('GET', '/api/session').as('session');
});Node-side task example
// cypress.config.js
const { defineConfig } = require('cypress');
const fs = require('node:fs');
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
on('task', {
readFixture(path) {
return fs.readFileSync(path, 'utf8');
}
});
return config;
}
}
});
// In a spec
cy.task('readFixture', 'fixtures/data.json').then((contents) => {
expect(contents).to.contain('example');
});Do not import the Node module into e2e.js; the task boundary is what keeps it in the Node process. Keeping the support bundle focused also reduces the amount of code Cypress must load before every spec.
Separate Cypress config and plugin module-format errors
The support file is compiled through Cypress’s support/spec pipeline. Configuration and plugin files follow Node module-selection rules. In Cypress 15.17.0 and later, Cypress selects a loader from the file extension and the nearest package.json; it no longer retries the other loader after a load failure.
| File or setting | How the format is selected | Compatible syntax |
|---|---|---|
.mjs |
ES modules | import/export |
.cjs |
CommonJS | require/module.exports |
.js with nearest package.json "type": "module" |
ES modules | import/export |
.js with omitted or "type": "commonjs" |
CommonJS | require/module.exports |
Align the extension, the nearest package’s type, and the syntax in cypress.config.js or plugin code. For example, use module.exports = defineConfig(...) in a CommonJS-selected file, or rename to .mjs and use export default defineConfig(...) for ESM. Do not apply this config-loader diagnosis to a browser-bundled support import without first confirming that the support file is actually the one named in the error.
A repeatable repair workflow
- Record the failing filename and line. Distinguish support, config, and plugin paths.
- Confirm testing type. Open Cypress’s end-to-end settings and verify that the option is under
e2e; usecomponentfor component tests. - Resolve one path. Use the default
cypress/support/e2e.jsor an explicitly configured custom path. - Remove ambiguity. Delete or rename duplicate matching support files.
- Minimize the entry file. Keep one known-good import, then reintroduce imports incrementally.
- Check dependency installation. Install missing packages in the Cypress project and verify relative paths.
- Audit runtime boundaries. Move filesystem, database, and other Node-only code to
setupNodeEventsand call it withcy.task(). - Fix config format separately. For Cypress 15.17.0 or later, align config/plugin extension and nearest package
type. - Re-run the same command in CI conditions. Use the same working directory, environment variables, dependency install mode, and case-sensitive path behavior.
Common failure branches and their fixes
The file is missing
Create cypress/support/e2e.js, correct e2e.supportFile, or intentionally set supportFile: false. Do not leave a path pointing to a file that was renamed during a migration.
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 problemsThe option is ignored or rejected
Move supportFile below the relevant testing-type key. A root-level setting reflects pre-Cypress-10 configuration and can produce an error while loading the config.
The file parses, but an import fails
Read the first dependency named in the stack. Check installation, package exports, relative paths, and whether the dependency assumes Node APIs. Replace the import with a browser-safe module or move the operation behind a task.
Only CI fails
Compare path case, current working directory, lockfile installation, and environment-dependent imports. A local cache or globally available package can hide a missing project dependency.
Changing import to require did not help
First verify which file failed. That change may be appropriate for a CommonJS-selected config file, but it does not make a Node-only dependency suitable for the browser support bundle and may be wrong for an ESM-selected config.
Free tools Windows power users keep installed
One-click scans. No signup required.
Performance and reliability considerations
- Every spec pays the startup cost of the support bundle, so avoid importing large libraries when a focused helper will do.
- Keep one stable entry file and make optional setup explicit rather than relying on duplicate discovery.
- Return the configuration object from
setupNodeEventsafter registering tasks or modifying it. - Prefer deterministic, project-local dependencies and lockfile-based installs so preparation failures are reproducible.
- Use the stack trace’s first actionable file and line instead of repeatedly changing unrelated module syntax.
Or skip the browser setup
If your immediate goal is a clean screenshot of a Cypress report, test page, or any URL rather than running Cypress itself, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server lets Claude, Cursor, or another MCP client use take_screenshot, get_page_info, and capture_pdf.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for the other parameters and capture options. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account to get started.
When the error is finally fixed
A successful repair has one unambiguous support entry file, a correctly scoped configuration, browser-safe imports, and a separate Node path for filesystem or service access. The Cypress runner should progress past test-file preparation and load the support code before the specs without a config-loader error.
Frequently Asked Questions
Can I disable the Cypress e2e support file entirely?
Yes. Set supportFile: false inside the e2e configuration object, and add any required commands or hooks directly where they are needed.
Recommended Free Tools
Does Cypress 15.17.0 change how e2e.js is loaded?
The 15.17.0 module-format selection rule applies to Cypress config and plugin files. The support entry remains part of the bundled browser pipeline; diagnose its imports and runtime compatibility separately.
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.
