Cypress "Your configFile is invalid" - cypress.config Errors

By Kaveh Alemi·Latchkey

Cypress loads cypress.config.{js,ts,mjs} before running anything. If that file throws while loading, exports the wrong shape, or uses a module syntax Cypress cannot read, the whole run aborts at startup.

What this error means

Cypress fails before any spec with "Your configFile is invalid" and a nested error - often a require that threw, an ESM/CommonJS mismatch, or an unknown config key. No tests execute.

Your configFile is invalid: /app/cypress.config.js

It threw an error when required, check the stack trace below:

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

Common causes

ESM/CommonJS mismatch in the config

A "type": "module" package with a require-based cypress.config.js, or an ESM-only import inside a CommonJS config, throws ERR_REQUIRE_ESM while loading.

Config throws or exports the wrong shape

A plugin/setupNodeEvents callback that throws, a missing env file read at load time, or an unknown top-level option makes Cypress reject the config.

How to fix it

Match the config module format to the package

Use defineConfig and the right extension for your module system.

// cypress.config.mjs  (ESM project)
import { defineConfig } from 'cypress';
export default defineConfig({
  e2e: { baseUrl: 'http://localhost:3000' },
});

Isolate what the config throws

1. Read the nested stack trace - Cypress prints the underlying error under the invalid-config message.
2. Move side-effectful reads (env files, dynamic requires) into setupNodeEvents, not top-level.
3. Remove unknown/typo’d config keys Cypress lists as invalid.

How to prevent it

• Use defineConfig for typed validation of the config shape.
• Keep the config extension consistent with the package "type".
• Avoid heavy side effects at config load time.

Frequently asked questions

Related guides

References

• GitHub Actions documentation