nwjs/nw.js · error · TypeError

Invalid 'key' format.

Error message

Invalid 'key' format.

What it means

Thrown inside keyToAccelerator() when the final segment of a shortcut key string (the part after the last '+') does not resolve to a known key in ALIAS_MAP. ALIAS_MAP covers a-z, 0-9, F1-F24, arrows, punctuation aliases, and DOM Level-3 code names. An unrecognized key token means the accelerator cannot be mapped to a hardware code, so the Shortcut cannot be constructed or registered.

Source

Thrown at src/resources/api_nw_shortcut.js:116

var handlers = {};

function keyToAccelerator(key) {
  key = key.toString();
  var parts = key.split('+');
  var maybeKey = parts.pop();
  var maybeModifiers = parts;

  var modifiers = {
    alt: false,
    command: false,
    ctrl: false,
    shift: false
  };

  maybeKey = ALIAS_MAP[maybeKey.toLowerCase()];
  if (!maybeKey) {
    throw new TypeError(OPTION_KEY_INVALID);
  }
  if (!maybeModifiers.every(function(m) {
    return modifiers[m.toLowerCase()] = MODIFIERS_REG.test(m);
  })) {
    throw new TypeError(OPTION_KEY_INVALID);
  }

  return {key: maybeKey, modifiers: modifiers};
}

function normalizeLocal(accelerator) {
  var modifiers = accelerator.modifiers;
  return [modifiers.alt, modifiers.command, modifiers.ctrl, modifiers.shift, accelerator.key].join('-');
}

function getRegistryLocal(accelerator) {
  var localKey = normalizeLocal(accelerator);
  return handlers[localKey];

View on GitHub (pinned to e15da848e9)

Solutions

  1. Verify the key token against ALIAS_MAP: use lowercase single chars (a-z, 0-9), lowercase code names (digit0, keya, arrowup), or symbolic aliases like 'enter', 'space', 'tab'.
  2. Strip trailing '+' and ensure the key segment is non-empty before constructing the Shortcut.
  3. If building key strings from user input, validate against a whitelist before passing to new nw.Shortcut().

Example fix

// before
new nw.Shortcut({ key: 'ctrl+xyz' });
// after
new nw.Shortcut({ key: 'ctrl+a' });
Defensive patterns

Strategy: validation

Validate before calling

// validate the key token before constructing
const ALIAS = /^[a-z0-9]|^f([1-9]|1[0-9]|2[0-4])$|^arrow(up|down|left|right)$|^(enter|space|tab|escape|backspace|delete|home|end|insert|pageup|pagedown)$/i;
function validKeyToken(k) { return ALIAS.test(k); }

Type guard

function isValidShortcutKey(keyStr) {
  if (typeof keyStr !== 'string') return false;
  const parts = keyStr.split('+');
  const last = parts.pop();
  // coarse check: last segment must look like a key, modifiers must be known
  return parts.every(m => /^(ctrl|alt|shift|command)$/i.test(m)) && last.length > 0;
}

Try / catch

try {
  const sc = new nw.Shortcut({ key: rawKey, active: fn });
} catch (e) {
  if (e.message === "Invalid 'key' format.") {
    console.warn('Ignoring invalid shortcut key:', rawKey);
  } else throw e;
}

Prevention

When it happens

Trigger: new nw.Shortcut({ key: 'ctrl+xyz' }) where 'xyz' is not in ALIAS_MAP; passing a fully qualified code name that is misspelled like 'Digit0' vs 'digi0'; passing an empty string key after split such as 'ctrl+' (empty token); using a locale-specific key label not in the alias set.

Common situations: Typos in key strings; copying key names from non-NW.js documentation that uses different naming conventions; constructing keys dynamically from user input without validation; using uppercase code names like 'KEYA' instead of the expected 'KeyA' or 'a'.

Related errors

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