cypress-io/cypress · error · Error

Incompatible versions detected, @cypress/grep 3.0.0+ require

Error message

Incompatible versions detected, @cypress/grep 3.0.0+ requires Cypress 10.0.0+

What it means

Thrown by the @cypress/grep plugin entry when the resolved Cypress config has no `specPattern` property. `specPattern` was introduced in Cypress 10 to replace the old `testFiles` array, so its absence is treated as definitive proof the host Cypress is pre-10. @cypress/grep 3.0.0+ is built against the Cypress 10+ config shape and cannot operate on older majors.

Source

Thrown at npm/grep/src/plugin.ts:27

interface CypressConfigOptions {
  expose?: Record<string, any>
  specPattern?: string | string[]
  excludeSpecPattern?: string | string[]
}

/**
 * Prints the "@cypress/grep" environment values if any.
 * @param {Cypress.ConfigOptions} config
 */
export function plugin (config: CypressConfigOptions): CypressConfigOptions {
  if (!config || !config.expose) {
    return config
  }

  const { expose } = config

  if (!config.specPattern) {
    throw new Error(
      'Incompatible versions detected, @cypress/grep 3.0.0+ requires Cypress 10.0.0+',
    )
  }

  debug('@cypress/grep plugin version %s', version)
  debug('Cypress config expose object: %o', expose)

  const grep = expose.grep ? String(expose.grep) : undefined

  if (grep) {
    console.log('@cypress/grep: tests with "%s" in their names', grep.trim())
  }

  const grepTags = expose.grepTags || expose['grep-tags']

  if (grepTags) {
    console.log('@cypress/grep: filtering using tag(s) "%s"', grepTags)
    const parsedGrep = parseGrep(null, grepTags)

View on GitHub (pinned to 0d85fdc912)

Solutions

1. Upgrade Cypress to 10.0.0 or newer (match the version called out in the message): `npm i -D cypress@latest`.
2. Confirm you migrated from cypress.json to cypress.config.{js,ts} — the specPattern property only exists on the new config.
3. Downgrade @cypress/grep to a 2.x release if you genuinely cannot upgrade Cypress.
4. Verify the plugin is wired in setupNodeEvents with the modern `(on, config) => { return plugin(config) }` shape.

Example fix

// before: cypress 9 + cypress.json
// plugins/index.js
module.exports = (on, config) => { require('@cypress/grep/src/plugin')(config); return config }
// after: cypress.config.ts (Cypress 10+)
import { defineConfig } from 'cypress'
import grep from '@cypress/grep/src/plugin'
export default defineConfig({
  e2e: {
    specPattern: 'cypress/e2e/**/*.cy.js',
    setupNodeEvents (on, config) { grep(config); return config },
  },
})

import semverLt from 'semver/functions/lt.js'
if (semverLt(Cypress.version, '10.0.0')) {
  throw new Error('Upgrade Cypress to >=10 to use this version of @cypress/grep')
}
if (!config.specPattern) { /* do not call grep plugin; use older grep */ }

const supportsSpecPattern = (c: any): boolean => Boolean(c && typeof c === 'object' && 'specPattern' in c && c.specPattern)

try { plugin(config) } catch (e) { if (/Incompatible versions/.test(e.message)) { /* upgrade Cypress or downgrade grep */ } else throw e }

When it happens

Trigger: Calling `plugin(config)` from setupNodeEvents where the passed `config` object lacks `specPattern`. This occurs when @cypress/grep 3.x is installed in a project running Cypress 9.x or earlier (which uses `config.testFiles` and a different plugin signature), or when a custom config factory strips the property.

Common situations: Upgrading @cypress/grep without upgrading Cypress; using an old cypress.json-based project with the new grep; or a CI matrix that pins an old Cypress version while pulling the latest grep.

Related errors

• ESM plugin config value '${name}' must be an array of string
• Could not read '${path}'.
• Failed to parse "${this.path}" as JSON AST Object. ${printPa
• Invalid grep burn value: ${grepBurn}
• Missing vite dev server port.

AI-assisted analysis of cypress-io/cypress@0d85fdc912 (2026-08-12). Data as JSON: /api/errors/a4eb2d17b8cf0ff5. Report an issue: GitHub.