cypress-io/cypress · error

The plugin register function must be called with an event…

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.

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
• ESM plugin config value
• Invalid grep burn value
• Invalid project path parameter

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

Appendix: 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)