{"record":{"id":"910f49b5f57a8ff8","repo":"affaan-m/ECC","slug":"unknown-claude-settings-merge-mode-options-mode","errorCode":null,"errorMessage":"Unknown Claude settings merge mode: ${options.mode}","messagePattern":"Unknown Claude settings merge mode: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/lib/install/claude-settings.js","lineNumber":486,"sourceCode":"\nfunction managedEntryFor(managedHooks, event, id) {\n  const entries = managedHooks && managedHooks[event];\n  if (!Array.isArray(entries)) {\n    return null;\n  }\n  return entries.find(entry => entry.id === id) || null;\n}\n\nfunction mergeManagedHooks(settings, managedHooks, options = {}) {\n  const validatedSettings = validateSettings(settings);\n  const desiredHooks = validateManagedHooks(managedHooks);\n  const previousHooks = options.previousManagedHooks === undefined\n    || options.previousManagedHooks === null\n    ? null\n    : validateRecordedManagedHooks(options.previousManagedHooks, 'previous managed hooks');\n  const repair = options.mode === 'repair' || options.repair === true;\n  if (options.mode !== undefined && options.mode !== 'merge' && options.mode !== 'repair') {\n    throw new Error(`Unknown Claude settings merge mode: ${options.mode}`);\n  }\n\n  let nextHooks = validatedSettings.hooks\n    ? cloneValue(validatedSettings.hooks)\n    : {};\n  const added = [];\n  const updated = [];\n  const unchanged = [];\n  const removed = [];\n\n  if (previousHooks) {\n    for (const [event, previousEntries] of Object.entries(previousHooks)) {\n      let eventEntries = nextHooks[event] ? cloneValue(nextHooks[event]) : [];\n      for (const previousEntry of previousEntries) {\n        if (managedEntryFor(desiredHooks, event, previousEntry.id)) continue;\n        const match = assertUnambiguousMatch(eventEntries, event, previousEntry.id);\n        if (!match) continue;\n        if (!isDeepStrictEqual(match.entry, previousEntry)) {","sourceCodeStart":468,"sourceCodeEnd":504,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/install/claude-settings.js#L468-L504","documentation":"mergeManagedHooks accepts only mode 'merge', 'repair', or undefined (plus a repair:true flag); any other value throws immediately. This validates the merge strategy before mutating the settings so callers cannot silently trigger unintended behavior with a typo'd mode.","triggerScenarios":"Calling mergeManagedHooks({ mode: 'force' }) or any misspelled/unsupported mode string ('Merge', 'replace', 'repair ' with trailing space); passing mode from unvalidated CLI/config input.","commonSituations":"A typo in a script or wrapper invoking the installer API, passing a CLI flag value straight through without validation, or copying an example that used an older API surface with different mode names.","solutions":["Change options.mode to one of 'merge' or 'repair' (or omit it entirely).","Check the call site for typos or case mismatches in the mode string.","If the mode comes from user input, validate/normalize it against the allowed set before calling.","Prefer passing repair: true over mode: 'repair' if that is how repair semantics are triggered in your code."],"exampleFix":"// before\nawait mergeManagedHooks({ settings, mode: 'replace' });\n// after\nawait mergeManagedHooks({ settings, mode: 'merge' });","handlingStrategy":"validation","validationCode":"const MODES = ['merge', 'repair', undefined];\nif (!MODES.includes(options.mode)) throw new Error(`mode must be 'merge', 'repair', or omitted`);","typeGuard":"function isMergeMode(v) { return v === undefined || v === 'merge' || v === 'repair'; }","tryCatchPattern":"try {\n  await mergeManagedHooks(opts);\n} catch (error) {\n  if (error.message.startsWith('Unknown Claude settings merge mode')) {\n    console.error(`Bad mode '${opts.mode}'; use 'merge' or 'repair'`);\n    return;\n  }\n  throw error;\n}","preventionTips":["Validate CLI/config values against an allowlist before passing options.mode","Use a constant (MODE_MERGE/MODE_REPAIR) instead of raw strings at call sites","Document the two valid modes wherever the API is wrapped","Trim/normalize user-supplied mode strings before use"],"tags":["invalid-argument","settings","merge","enum"],"backgroundTag":"invalid-enum-value","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}