nwjs/nw.js · error · TypeError

'shortcut' argument is not an instance of nw.Shortcut

Error message

'shortcut' argument is not an instance of nw.Shortcut

What it means

Thrown by nw.Shortcut.registerGlobalHotKey(shortcut) when the argument is not an instance of Shortcut (checked via shortcut instanceof Shortcut). The method needs a Shortcut because it reads shortcut._accelerator (the parsed internal representation) and calls shortcut.emit('failed') on registration failure. A plain object or wrong type lacks these.

Source

Thrown at src/resources/api_nw_shortcut.js:197

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

  this.key = option.key;
  this.active = option.active;
  this.failed = option.failed;

  this._accelerator = keyToAccelerator(option.key);
}

nw.require('util').inherits(Shortcut, EventEmitter);

Shortcut.registerGlobalHotKey = function(shortcut) {
  if (!(shortcut instanceof Shortcut)) {
    throw new TypeError(ARUGMENT_NOT_SHORTCUT);
  }

  if(nwShortcutBinding.registerAccelerator(shortcut._accelerator)) {
    registerLocal(shortcut);
  } else {
    shortcut.emit('failed', new Error(UNABLE_REGISTER_HOTKEY));
  }
};

Shortcut.unregisterGlobalHotKey = function(shortcut) {
  if (!(shortcut instanceof Shortcut)) {
    throw new TypeError(ARUGMENT_NOT_SHORTCUT);
  }

  var handler = getRegistryLocal(shortcut._accelerator);
  if(handler && nwShortcutBinding.unregisterAccelerator(shortcut._accelerator)) {
    unregisterLocal(shortcut);
  } else {

View on GitHub (pinned to e15da848e9)

Solutions

1. Construct the shortcut first: const sc = new nw.Shortcut({ key: 'ctrl+a', active: fn }); then nw.Shortcut.registerGlobalHotKey(sc).
2. For cross-realm objects, duck-type on _accelerator or reconstruct the Shortcut in the current realm before registering.
3. Add an instanceof check in your own wrapper to fail with a clearer message.

Example fix

// before
nw.Shortcut.registerGlobalHotKey({ key: 'ctrl+a' });
// after
const sc = new nw.Shortcut({ key: 'ctrl+a', active: fn });
nw.Shortcut.registerGlobalHotKey(sc);

if (!(shortcut instanceof nw.Shortcut)) {
  throw new TypeError('registerGlobalHotKey requires an nw.Shortcut instance');
}
nw.Shortcut.registerGlobalHotKey(shortcut);

function isShortcutInstance(o) { return o instanceof nw.Shortcut; }

When it happens

Trigger: nw.Shortcut.registerGlobalHotKey({ key: 'ctrl+a' }) (plain object instead of Shortcut instance); passing the key string; passing a Menu or Tray object by mistake; passing a shortcut created in a different context/realm whose prototype chain differs.

Common situations: Forgetting to call new nw.Shortcut() first; cross-realm objects (e.g. from an iframe or different window) where instanceof fails despite correct shape; copy-paste that drops the construction step.

Related errors

• Invalid option.
• Shortcut requires 'key' to specify key combinations.
• Invalid 'key' format.
• Invalid option.
• Shortcut requires 'key' to specify key combinations.

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