Cypress refuses to start with 'Your configFile is invalid'
Your configFile is invalid: /path/to/cypress.config.tsShort answer
Cypress could not load cypress.config.js or .ts, or found something wrong in it. The lines under the message say which. Common causes are an ES module project with a CommonJS config, a TypeScript config named for the wrong module format, setupNodeEvents in the wrong place, an invalid devServer, or an error thrown while the file loads.
Fix it fast
1Find out which cause you have
Cypress prints the reason in the lines under the first message: a stack trace, or a description of the setting that is wrong. Start Cypress from the project folder and read those lines before you change anything. The causes below are matched to what they say.
npx cypress open # read everything printed after: Your configFile is invalid:2Match what you see, then jump to its fix
- 1
package.json has "type": "module" and cypress.config.js uses require and module.exports, or the project has no "type" and the config uses import and export.An ES module project with a CommonJS config, or the reverseFix - 2
The project uses cypress.config.ts, and the error appears right after you changed "type", renamed the file, or changed compilerOptions.module in tsconfig.json.A TypeScript config named or typed for the wrong module formatFix - 3
The text under Your configFile is invalid says that setupNodeEvents must be defined with a certain signature.setupNodeEvents is not a function with the (on, config) signatureFix - 4
The message names component.devServer.component.devServer is missing a framework or bundlerFix - 5
The stack trace points at a line inside cypress.config.* or at a file it imports, for example a missing package or a syntax error.The config file itself throws while it loadsFix
- 1
What does the error look like?
Your configFile is invalid: /path/to/cypress.config.tsYour configFile threw an error from: /path/to/cypress.config.tsCypress stops before any test runs
Cause 1 of 5
An ES module project with a CommonJS config, or the reverse
1Check
Since Cypress 15.17.0 Cypress decides the format before it loads the file, the way Node.js does. A .mjs file is ESM, a .cjs file is CommonJS, and a .js file is ESM only when the nearest package.json has "type": "module". If loading fails, Cypress does not try the other format.
grep -n "\"type\"" package.json
head -n 5 cypress.config.js2Fix
Make the file and the project agree. In a module project that has a CommonJS config, rename the file to cypress.config.cjs. Or write the config with import and export default.
// ES module project: cypress.config.js
import { defineConfig } from 'cypress'
export default defineConfig({
e2e: {
setupNodeEvents(on, config) {},
},
})3Verify
Start Cypress again and check that the message is gone.
npx cypress openConfirmed by docs.cypress.io
Cause 2 of 5
A TypeScript config named or typed for the wrong module format
1Check
For TypeScript configs Cypress takes the format from the file extension and package.json, and ignores compilerOptions.module. Your tsconfig still has to match. The TypeScript page also states that Cypress needs TypeScript 5.x, 6.x or 7.x.
npm ls typescript
grep -n "\"module\"\\|\"type\"" tsconfig.json package.json2Fix
For CommonJS, set compilerOptions.module to commonjs and name the file cypress.config.cts, or keep cypress.config.ts with "type" omitted or set to commonjs. For ESM, use an ESM module setting such as NodeNext or ES2022 together with "type": "module" and cypress.config.ts, or name the file cypress.config.mts.
// tsconfig.json, ESM variant
{ "compilerOptions": { "module": "NodeNext" } }3Verify
Start Cypress again. The config loads.
npx cypress openConfirmed by docs.cypress.io
Cause 3 of 5
setupNodeEvents is not a function with the (on, config) signature
1Check
setupNodeEvents goes inside e2e or component, and it takes two arguments: on and config. Look for it at the top level of the object, or assigned a value that is not a function.
grep -n -B2 -A6 "setupNodeEvents" cypress.config.*2Fix
Move it inside e2e (or component) and write it as a function that receives on and config. Return config if you changed it.
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
return config
},
},
})3Verify
Start Cypress again.
npx cypress openConfirmed by docs.cypress.io
Cause 4 of 5
component.devServer is missing a framework or bundler
1Check
Component testing needs devServer. You normally set framework and bundler, or pass a function that returns a dev server.
grep -n -A6 "devServer" cypress.config.*2Fix
Give devServer a supported framework and a bundler.
component: {
// example values from the Cypress docs: use the framework and bundler of your own app
devServer: { framework: 'create-react-app', bundler: 'webpack' },
},3Verify
Open component testing again.
npx cypress openConfirmed by docs.cypress.io
Cause 5 of 5
The config file itself throws while it loads
1Check
The message says the file threw an error when it was required, and the stack trace is printed below it. The trace names the real error and the line.
npx cypress open2Fix
Fix the error the trace names: install the package it cannot find, or correct the syntax at that line.
# for a missing package named in the trace
npm install --save-dev the-package-named-in-the-trace3Verify
Start Cypress again. The message is gone.
npx cypress openConfirmed by raw.githubusercontent.com
How do I stop it coming back?
- Keep the config in the same module format as the rest of the project, and name .cjs or .mjs files on purpose.
- Use defineConfig, so the editor flags a wrongly shaped config before you start Cypress.
- After you change package.json type or tsconfig module, start Cypress once to check the config still loads.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Web apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
ESLint cannot decide which copy of the @typescript-eslint plugin to use
The message lists two file paths for the same plugin, each with the name of the config that loaded it
ESLint found the same plugin at two different file paths and will not pick one.
3 causes, each with a fixWeb apps
ESLint says it cannot resolve a path to a module that does exist
Unable to resolve path to module 'react'. import/no-unresolved
import/no-unresolved fails when eslint-plugin-import cannot find the file or package on disk with its resolver.
4 causes, each with a fixWeb apps
ESLint was configured to run using parserOptions.project, but the file is not in the TSConfig
However, that TSConfig does not include this file
Type-aware linting needs every linted file to belong to a TypeScript project.
4 causes, each with a fixWeb apps
Upgrading to Next.js 16: middleware becomes proxy, and the other things that break
Missing Required default.js for Parallel Route
Next.js 16 renames middleware.ts to proxy.ts and its exported function to proxy.
6 causes, each with a fixWeb apps
TypeScript cannot resolve import './globals.css' in Next.js
ts(2882)
TypeScript now checks imports like import './globals.css' when noUncheckedSideEffectImports is on, and it finds no type for a CSS file.
2 causes, each with a fix