moeru-ai/airi · error · Error

Invalid accelerator: unknown key "${token}"

Error message

Invalid accelerator: unknown key "${token}"

What it means

Thrown by `normalizeKeyToken()` in the global-shortcut accelerators module when a key token cannot be matched against any known key. The normalizer first checks the canonical `KEY_NAMES` set, then a small `KEY_ALIASES` map, then single-letter (`Key<A-Z>`) and single-digit (`Digit<0-9>`) shorthand; if none match, the token is rejected as an unknown key. This runs as part of `parseAccelerator()` for the non-modifier token of the accelerator string.

Source

Thrown at packages/stage-shared/src/global-shortcut/accelerators.ts:270

    return token

  const aliased = KEY_ALIASES.get(token)
  if (aliased !== undefined)
    return aliased

  if (SINGLE_LETTER_RE.test(token)) {
    const candidate = `Key${token.toUpperCase()}`
    if (LETTER_KEYS.has(candidate))
      return candidate
  }

  if (SINGLE_DIGIT_RE.test(token)) {
    const candidate = `Digit${token}`
    if (DIGIT_KEYS.has(candidate))
      return candidate
  }

  throw new Error(`Invalid accelerator: unknown key "${token}"`)
}

/**
 * Returns the canonical modifier for a token, or `undefined` if the
 * token is not a modifier (i.e. probably a key).
 */
function lookupModifierToken(token: string): ShortcutModifier | undefined {
  return MODIFIER_ALIASES.get(token.toLowerCase())
}

/**
 * Parses a string accelerator into its canonical structured form.
 *
 * Use when:
 * - Accepting an accelerator from author code, settings UI, or config
 *   file
 * - Validating user input
 *

View on GitHub (pinned to 27111382b4)

Solutions

1. Use a key token the parser recognizes: a single letter (`K`), single digit (`5`), a canonical W3C code (`KeyK`, `Digit5`, `ArrowUp`, `Escape`), or an alias (`Up`, `Esc`).
2. Check `KEY_NAMES` and `KEY_ALIASES` in the module for the accepted token set before authoring the accelerator.
3. If you need a key not yet supported (e.g. function keys), extend `KEY_NAMES`/`KEY_ALIASES` and ensure the Electron serialization overrides cover it, rather than passing an unknown token.
4. Validate user-provided accelerator strings with `parseAccelerator` in a try/catch and surface a clear error in the settings UI.

Example fix

// before
parseAccelerator('CmdOrCtrl+F1') // F1 not in KEY_NAMES

// after
parseAccelerator('CmdOrCtrl+P')

import { parseAccelerator } from '@proj-airi/stage-shared/global-shortcut/accelerators'

function tryParseAccelerator(input: string) {
  try {
    return { accelerator: parseAccelerator(input), error: undefined }
  } catch (e) {
    return { accelerator: undefined, error: e as Error }
  }
}

const { accelerator, error } = tryParseAccelerator(userInput)
if (error) showUser(`Invalid shortcut: ${error.message}`)

const SINGLE_LETTER_RE = /^[A-Z]$/i
const SINGLE_DIGIT_RE = /^\d$//

function looksLikeValidKeyToken(token: string): boolean {
  return SINGLE_LETTER_RE.test(token) || SINGLE_DIGIT_RE.test(token) || KEY_NAMES.has(token) || KEY_ALIASES.has(token)
}

// NOTE: KEY_NAMES and KEY_ALIASES must be imported/re-exported from the module to use this guard in caller code.

try {
  const accel = parseAccelerator(input)
  register(accel)
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid accelerator:')) {
    showUser(`That shortcut key is not recognized. Use a letter, digit, or a known key name.`)
    return
  }
  throw e
}

When it happens

Trigger: Calling `parseAccelerator(input)` where the key token is not a recognized name, alias, single letter, or single digit — e.g. `CmdOrCtrl+F1` (function keys not in KEY_NAMES), `Ctrl+??`, `Shift+foobar`, or a token with stray punctuation. Whitespace is trimmed before matching, but unknown multi-character key names still fail.

Common situations: User-configured or settings-file shortcuts using key names the parser does not recognize (function keys, numpad names, locale-specific keys, punctuation not in the alias map); typos; accelerators copied from another app's format that uses different key names.

Related errors

• Invalid Godot stage scene input payload.
• Invalid JSON for componentProps: ${(error as Error).message}
• componentName is required to spawn a widget.
• id is required to update a widget.
• id is required to remove a widget.

AI-assisted analysis of moeru-ai/airi@27111382b4 (2026-08-12). Data as JSON: /api/errors/10b6f8b818452324. Report an issue: GitHub.