cypress-io/cypress · error · Error

Invalid grep burn value: ${grepBurn}

Error message

Invalid grep burn value: ${grepBurn}

What it means

Thrown by the @cypress/grep register logic after resolving the `burn` value (number of times to repeat each filtered test). The guard requires grepBurn to be a positive integer (Cypress._.isInteger AND >= 1); default is 1. A non-integer (float, NaN, string) or a value below 1 is rejected because the burn loop cannot meaningfully repeat a fractional or zero/negative number of times.

Source

Thrown at npm/grep/src/register.ts:63

  if (!grep && !grepTags && !burnSpecified && !grepUntagged) {
    debugInstance('Nothing to grep, version %s', version)

    return
  }

  const grepBurn: number =
    Cypress.expose('grepBurn') ||
    Cypress.expose('grep-burn') ||
    Cypress.expose('burn') ||
    1

  const omitFiltered: boolean =
    Cypress.expose('grepOmitFiltered') || Cypress.expose('grep-omit-filtered')

  debugInstance('grep %o', { grep, grepTags, grepBurn, omitFiltered, version })
  if (!Cypress._.isInteger(grepBurn) || grepBurn < 1) {
    throw new Error(`Invalid grep burn value: ${grepBurn}`)
  }

  const parsedGrep = parseGrep(grep, grepTags)

  debugInstance('parsed grep %o', parsedGrep)

  if (it.name === 'itGrep') {
    debugInstance('already registered @cypress/grep')

    return
  }

  // @ts-expect-error - it is missing only, skip, and retries which are overridden below
  it = function itGrep (name: string, options: any, callback?: Func | AsyncFunc): Mocha.Test | void[] {
    if (typeof options === 'function') {
      callback = options
      options = {}
    }

View on GitHub (pinned to 0d85fdc912)

Solutions

1. Set burn to a positive integer: `--env grepBurn=3` or `CYPRESS_GREP_BURN=3`.
2. If you intended 'no repetition', omit the burn env entirely (it defaults to 1).
3. Ensure env vars are coerced to numbers before passing; avoid strings like `--env grepBurn="3"` if your shell/runner mangles them.
4. Check for accidental `grep-burn` / `burn` aliases overriding a correct `grepBurn`.

Example fix

// before
CYPRESS_GREP_BURN=2.5 cypress run --env grep=@smoke
// after
CYPRESS_GREP_BURN=3 cypress run --env grep=@smoke

function resolveBurn(raw: unknown): number {
  const n = Number(raw)
  if (!Number.isInteger(n) || n < 1) return 1 // sane default instead of throwing
  return n
}

const isPositiveInt = (v: unknown): v is number => typeof v === 'number' && Number.isInteger(v) && v >= 1

try { /* register grep */ } catch (e) { if (/Invalid grep burn value/.test(e.message)) { Cypress.expose('grepBurn', 1); /* retry registration */ } else throw e }

When it happens

Trigger: Setting the grep burn via env/expose to a non-integer or <1 value, e.g. `CYPRESS_GREP_BURN=2.5`, `--env grepBurn=0`, `--env burn=-1`, or `--env grepBurn=abc`. The value is read through Cypress.expose('grepBurn') | Cypress.expose('grep-burn') | Cypress.expose('burn'), defaulting to 1.

Common situations: Passing a float by accident (2.5), passing 0 expecting 'no burn', passing a string because the env var was not coerced, or a CI script interpolating an empty/undefined variable that becomes NaN.

Related errors

• Invalid project path parameter: ${options.project}
• Unknown component name "${componentName}"
• No file name specified. This is required to generate a new C
• Incompatible versions detected, @cypress/grep 3.0.0+ require
• ESM plugin config value '${name}' must be an array of string

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