Cypress "Your configFile is invalid" in CI

By Daniel Zoghalchali·Latchkey

Cypress failed to load cypress.config.js. The file threw while being required - a syntax error, a bad import, an unknown config option, or an ESM/CommonJS format mismatch.

What this error means

Cypress aborts at startup with "Your configFile is invalid. It threw an error when required" plus the underlying exception, or "must export a valid configuration." No specs run.

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

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

SyntaxError: Cannot use import statement outside a module
    at compileFunction (node:vm)

Common causes

ESM/CommonJS mismatch

Using import in a .js config without "type": "module", or module.exports in an ESM context, makes Node throw while requiring the file.

Syntax error or unknown option

A typo, a bad require, or a config key Cypress does not recognize (often a v9-style option after upgrading to v10+) invalidates the file.

How to fix it

Match the config module format

Use defineConfig and the format that matches your package.json type.

// cypress.config.js (CommonJS)
const { defineConfig } = require('cypress');
module.exports = defineConfig({
  e2e: { baseUrl: 'http://localhost:3000' },
});

Fix unknown options and imports

1. Read the printed stack trace; it names the failing line or option.
2. Remove or migrate options not valid in your Cypress major version.
3. Use cypress.config.mjs if the project is ESM-only.

How to prevent it

• Generate config with defineConfig for validation and types.
• Keep the config module format consistent with package.json.
• Run cypress verify/a smoke run after upgrading Cypress.

Frequently asked questions

Related guides

References

• GitHub Actions documentation