What causes "'active' must be a valid function." in nwjs/nw.js?

Pass an actual function reference: { key: 'ctrl+a', active: () => {} }.

nwjs/nw.js · error · TypeError

'active' must be a valid function.

Error message

'active' must be a valid function.

What it means

Thrown by the Shortcut constructor when option.hasOwnProperty('active') is true but typeof option.active !== 'function'. The 'active' callback is invoked when the hotkey is pressed, so it must be callable. The constructor validates this eagerly at construction time.

Source

Thrown at src/resources/api_nw_shortcut.js:162

  delete handlers[localKey];
}

function Shortcut(option) {
  if (!(this instanceof Shortcut)) {
    return new Shortcut(option);
  }

  EventEmitter.apply(this, arguments);

  if (typeof option != 'object')
    throw new TypeError(OPTION_INVALID);

  if (!option.key)
    throw new TypeError(OPTION_KEY_REQUIRED);

  if (option.hasOwnProperty('active')) {
    if (typeof option.active != 'function')
      throw new TypeError(OPTION_ACTIVE_INVALID);
  }

  if (option.hasOwnProperty('failed')) {
    if (typeof option.failed != 'function')
      throw new TypeError(OPTION_FAILED_INVALID);
  }

  var self = this;

  this.on('active', function() {
    if (!self.active) return;
    if (typeof self.active != 'function')
      throw new TypeError(OPTION_ACTIVE_INVALID);
    self.active.apply(self, arguments);
  });

  this.on('failed', function() {
    if (!self.failed) return;

View on GitHub (pinned to e15da848e9)

Solutions

Pass an actual function reference: { key: 'ctrl+a', active: () => {} }.
If loading config from JSON, resolve the handler by name at runtime: { key: cfg.key, active: handlers[cfg.activeName] }.
Omit the active property entirely if you do not need it; it is optional.

Example fix

// before
new nw.Shortcut({ key: 'ctrl+a', active: 'onActivate' });
// after
new nw.Shortcut({ key: 'ctrl+a', active: onActivate });

Defensive patterns

Strategy: type-guard

Validate before calling

if ('active' in option && typeof option.active !== 'function') {
  throw new TypeError('option.active must be a function');
}

Type guard

function isActiveValid(o) { return !o.hasOwnProperty('active') || typeof o.active === 'function'; }

Prevention

Pass function references, never handler name strings.
When loading config from JSON, resolve named handlers from a registry first.
Omit active if unused rather than setting a placeholder non-function.

When it happens

Trigger: new nw.Shortcut({ key: 'ctrl+a', active: 'handlerName' }) (string instead of function); new nw.Shortcut({ key: 'ctrl+a', active: true }); passing an object whose active property was serialized from JSON (functions do not survive serialization).

Common situations: Loading shortcut config from a JSON file (JSON has no function type); referencing a handler by name string instead of the function reference; scope/import errors leaving active undefined-ish but present.

Related errors

AI-assisted analysis of nwjs/nw.js@e15da848e9 (2026-08-13). Data as JSON: /api/errors/273b731329faf477. Report an issue: GitHub.