nwjs/nw.js · error · TypeError

'failed' must be a valid function.

Error message

'failed' must be a valid function.

What it means

Thrown by the Shortcut constructor when option.hasOwnProperty('failed') is true but typeof option.failed !== 'function'. The 'failed' callback is invoked when registration or unregistration of the hotkey fails, so it must be callable. Validated eagerly at construction time.

Source

Thrown at src/resources/api_nw_shortcut.js:167

    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;
    if (typeof self.failed != 'function')
      throw new TypeError(OPTION_FAILED_INVALID);
    self.failed.apply(self, arguments);
  });

View on GitHub (pinned to e15da848e9)

Solutions

1. Pass a real function for failed: { key: 'ctrl+a', failed: (err) => console.error(err) }.
2. Resolve the handler from a name registry when loading config from JSON.
3. Omit failed if you do not need failure notification; it is optional.

Example fix

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

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

function isFailedValid(o) { return !o.hasOwnProperty('failed') || typeof o.failed === 'function'; }

When it happens

Trigger: new nw.Shortcut({ key: 'ctrl+a', failed: 'errHandler' }) (string); new nw.Shortcut({ key: 'ctrl+a', failed: {} }); failed loaded from a JSON-deserialized config.

Common situations: JSON config round-trip losing function values; passing a config object shared with another library that uses a different shape; forgetting that 'failed' must be a function not a description string.

Related errors

• 'active' must be a valid function.
• Invalid option.
• Shortcut requires 'key' to specify key combinations.
• Invalid 'key' format.
• Invalid option.

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