cypress-io/cypress · error

The plugin register function must be called with an event as

Error message

The plugin register function must be called with an event as its 1st argument. You passed '${event}'.

What it means

Thrown by EventRegistrar.registerEvent when its first argument fails _.isString. The registrar expects plugin authors to call on(eventName, callback) where eventName is a known event name string; passing undefined, a number, null, or an object triggers this guard. The error message echoes the offending value so the plugin author can see what they passed.

Source

Thrown at packages/data-context/src/data/EventRegistrar.ts:33

  }

  executeNodeEvent (event: string, args: any[]) {
    debug(`execute plugin event '${event}' Node '${process.version}' with args: %o %o %o`, ...args)

    const evtFn = this._registeredEvents[event]

    if (typeof evtFn !== 'function') {
      throw new Error(`Missing event for ${event}`)
    }

    return evtFn(...args)
  }

  registerEvent (event: string, callback: Function) {
    debug(`register event '${event}'`)

    if (!_.isString(event)) {
      throw new Error(`The plugin register function must be called with an event as its 1st argument. You passed '${event}'.`)
    }

    if (!_.isFunction(callback)) {
      throw new Error(`The plugin register function must be called with a callback function as its 2nd argument. You passed '${callback}'.`)
    }

    this._registeredEvents[event] = callback
  }

  reset () {
    this._registeredEvents = {}
  }
}

View on GitHub (pinned to 0d85fdc912)

Solutions

1. Inspect the value passed as the first argument to on() — it must be a string literal like 'before:spec' or 'task'.
2. If using an imported constant, verify the import resolves (it is likely undefined).
3. Add a typeof check before calling on() in your plugin if the event name is dynamic.
4. Run with DEBUG=cypress:plugins to see the register-event log line that includes the value.

Example fix

// before
import { WrongName } from 'some-pkg'
setupNodeEvents(on) { on(WrongName, () => null) } // WrongName is undefined
// after
setupNodeEvents(on) { on('before:spec', () => null) }

function safeRegister (registrar, event, cb) {
  if (typeof event !== 'string' || !event) {
    throw new TypeError(`event must be a non-empty string, got ${typeof event}`)
  }
  registrar.registerEvent(event, cb)
}

function isEventName (v: unknown): v is string {
  return typeof v === 'string' && v.length > 0
}

When it happens

Trigger: A plugin's setupNodeEvents calls on(undefined, fn) (typically because the event name was misspelled or destructured from a non-existent export), or a plugin passes a numeric/object identifier. Often the result of `const { BeforeSpec } = ...` destructuring that returned undefined.

Common situations: Typo in event name variable, importing an event-name constant that does not exist (undefined), or third-party plugin calling on() with a computed value that evaluates to a non-string.

Related errors

• The plugin register function must be called with a callback
• Missing event for ${event}
• Invalid project path parameter: ${options.project}
• Unknown component name "${componentName}"
• No file name specified. This is required to generate a new C

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