{"record":{"id":"9a62472687ec4fbe","repo":"stablyai/orca","slug":"could-not-normalize-legacy-binding-for-failedac","errorCode":null,"errorMessage":"Could not normalize legacy binding for \"${failedActionIds.join('\", \"')}.\"","messagePattern":"Could not normalize legacy binding for \"(.+?)\\.\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/keybindings/keybinding-file.ts","lineNumber":378,"sourceCode":"  const failedActionIds: KeybindingActionId[] = []\n  for (const actionId of toSeed) {\n    const normalized = normalizeKeybindingArrayForAction(actionId, legacyBindings[actionId] ?? [])\n    if (!Array.isArray(normalized)) {\n      failedActionIds.push(actionId)\n      continue\n    }\n    pins.push([actionId, normalized])\n  }\n  const snapshot =\n    pins.length > 0\n      ? writeActivePlatformSection(path, platform, current.commonOverrides, (activePlatform) => {\n          for (const [actionId, normalized] of pins) {\n            activePlatform[actionId] = normalized\n          }\n        })\n      : current\n  if (failedActionIds.length > 0) {\n    throw new Error(`Could not normalize legacy binding for \"${failedActionIds.join('\", \"')}\".`)\n  }\n  return { seeded: pins.length > 0, snapshot }\n}\n\n// Why: the one-shot seed migration and Settings writes must produce the same\n// on-disk document shape; a single assembly path keeps them from drifting.\nfunction writeActivePlatformSection(\n  path: string,\n  platform: NodeJS.Platform,\n  fallbackCommonOverrides: KeybindingOverrides,\n  mutateActivePlatform: (activePlatform: JsonObject) => void\n): KeybindingFileSnapshot {\n  const keybindingPlatform = getKeybindingPlatform(platform)\n  const readResult = readJsonDocument(path)\n  if (!readResult.document) {\n    // Why: writes must never replace a user-owned file that could not be\n    // parsed; callers surface the error (or retry the migration) after repair.\n    throw new Error(readResult.error ?? 'Could not read keybindings file.')","sourceCodeStart":360,"sourceCodeEnd":396,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/main/keybindings/keybinding-file.ts#L360-L396","documentation":"Thrown at the end of the legacy-binding seed migration when one or more actionIds could not be normalized (normalizeKeybindingArrayForAction returned a non-array result). The error lists every failed actionId so the user can see which legacy bindings were rejected. The successful pins are still written before this throws.","triggerScenarios":"Migrating an old keybindings file whose entries for certain actionIds use a syntax the current normalizer rejects (renamed actions, deprecated key tokens, malformed combos). The migration writes the valid bindings then raises so the user knows some did not carry over.","commonSituations":"Upgrading Orca across a version that renamed/removed keybinding actions or changed token grammar (e.g. 'Cmd' → 'Meta'). Importing a keybindings file from another OS or an older major version.","solutions":["Open the keybindings file and fix or remove the listed actionIds' bindings using current token syntax.","Re-run the migration (it is idempotent — already-written pins are skipped).","If an actionId was removed entirely, delete that legacy entry.","Re-record those shortcuts through the Settings UI."],"exampleFix":"// before (legacy file)\n{ \"oldActionName\": \"Cmd+Shift+P\" }\n// after (after fixing to current actionId + array form)\n{ \"platforms\": { \"darwin\": { \"command.palette.open\": [\"Cmd+Shift+P\"] } } }","handlingStrategy":"try-catch","validationCode":"const failed = actionIds.filter((id) => !Array.isArray(normalizeKeybindingArrayForAction(id, legacyBindings[id] ?? [])))\nif (failed.length) await runKeybindingsRepairUI(failed)","typeGuard":"function canNormalizeLegacy(actionId: KeybindingActionId, legacy: readonly string[]): boolean {\n  return Array.isArray(normalizeKeybindingArrayForAction(actionId, legacy))\n}","tryCatchPattern":"try { seedLegacyKeybindings(path, platform) }\ncatch (e) { if (/Could not normalize legacy binding/.test(String((e as Error).message))) openKeybindingsRepair(extractFailedActionIds(e)); else throw e }","preventionTips":["Fix or remove legacy bindings listed in the error before re-running the migration.","Keep actionIds and token grammar current when upgrading Orca.","Re-record migrated shortcuts via the Settings UI."],"tags":["keybindings","migration","legacy","parse"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}