Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Cypress refuses to start with 'Your configFile is invalid'

ErrorYour configFile is invalid: /path/to/cypress.config.ts

Short 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.

  • Applies to Cypress 15.17 and later, Node.js 22, TypeScript 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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:
  2. 2Match what you see, then jump to its fix

    1. 1package.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. 2The 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. 3The 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. 4The message names component.devServer.component.devServer is missing a framework or bundlerFix
    5. 5The 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

What does the error look like?

  • Your configFile is invalid: /path/to/cypress.config.ts
  • Your configFile threw an error from: /path/to/cypress.config.ts
  • Cypress 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.js

2Fix

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 open

Confirmed by docs.cypress.io

Did this fix it?

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.json

2Fix

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 open

Confirmed by docs.cypress.io

Did this fix it?

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 open

Confirmed by docs.cypress.io

Did this fix it?

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 open

Confirmed by docs.cypress.io

Did this fix it?

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 open

2Fix

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-trace

3Verify

Start Cypress again. The message is gone.

npx cypress open

Confirmed by raw.githubusercontent.com

Did this fix it?

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:

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.