{"record":{"id":"d5b169bc70cef3d6","repo":"affaan-m/ECC","slug":"invalid-label-expected-at-least-one-hook-event","errorCode":null,"errorMessage":"Invalid ${label}: expected at least one hook event","messagePattern":"Invalid (.+?): expected at least one hook event","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"scripts/lib/install/claude-settings.js","lineNumber":132,"sourceCode":"    ) {\n      throw new Error(`Invalid managed hook handler at ${label}: invalid allowedEnvVars`);\n    }\n    return;\n  }\n  if (!isNonEmptyString(hook.prompt)) {\n    throw new Error(`Invalid managed hook handler at ${label}: invalid prompt`);\n  }\n  if (hook.model !== undefined && !isNonEmptyString(hook.model)) {\n    throw new Error(`Invalid managed hook handler at ${label}: invalid model`);\n  }\n}\n\nfunction validateManagedHooks(managedHooks, label = 'managed hooks') {\n  if (!isJsonObject(managedHooks)) {\n    throw new Error(`Invalid ${label}: expected a JSON object`);\n  }\n  if (Object.keys(managedHooks).length === 0) {\n    throw new Error(`Invalid ${label}: expected at least one hook event`);\n  }\n\n  const seenIds = new Set();\n  for (const [event, entries] of Object.entries(managedHooks)) {\n    if (!VALID_EVENTS.has(event)) {\n      throw new Error(`Invalid ${label}: unsupported hook event \"${event}\"`);\n    }\n    if (!Array.isArray(entries)) {\n      throw new Error(`Invalid ${label}.${event}: expected an array`);\n    }\n    if (entries.length === 0) {\n      throw new Error(`Invalid ${label}.${event}: expected at least one hook entry`);\n    }\n\n    entries.forEach((entry, index) => {\n      if (!isJsonObject(entry)) {\n        throw new Error(\n          `Invalid managed hook entry at ${label}.${event}[${index}]: expected a JSON object`","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/scripts/lib/install/claude-settings.js#L114-L150","documentation":"A managed hooks config must contain at least one hook event key. validateManagedHooks throws this error when the config is a plain object but has zero keys ({}), because installing an empty hook set via this API is treated as a mistake rather than a no-op.","triggerScenarios":"Calling materializeManagedHooks/validateManagedHooks with {} or an object whose keys were all filtered out; computing a diff where all hooks were removed and passing the resulting empty object as the desired set.","commonSituations":"A filter step (by event, by agent) removed every hook before install; a fresh project generating hooks from an empty list; migrating configs where the source hooks block was empty; conditional code that builds hooks but skips adding any.","solutions":["Provide at least one hook event in the object, e.g. {\"SessionStart\":[{type:'command', command:'...'}]}.","If you intend to remove all hooks, use the API's removal/uninstall path rather than validating an empty desired set.","Fix upstream filters so they do not silently drop every hook; log when the filtered set is empty.","Generate hooks before validation, or short-circuit the install call when the hook list is empty."],"exampleFix":"// before\nvalidateManagedHooks({});\n// after\nconst hooks = { \"SessionStart\": [{ \"type\": \"command\", \"command\": \"node hooks/session-start.js\" }] };\nvalidateManagedHooks(hooks);","handlingStrategy":"validation","validationCode":"if (Object.keys(desiredHooks).length === 0) { throw new Error('Refusing to install an empty managed hooks set — use the uninstall API or fix the filter'); }","typeGuard":"const nonEmptyHooks = (v) => v !== null && typeof v === 'object' && Object.keys(v).length > 0;","tryCatchPattern":"try { installHooks(desired); } catch (e) { if (e.message.includes('expected at least one hook event')) { console.error('Desired hooks resolved to empty — check filters/generators:', e.message); process.exitCode = 1; } else throw e; }","preventionTips":["Log when a filter reduces the hook set to zero.","Use the dedicated removal path for deleting all hooks.","Generate at least one hook event before install."],"tags":["config","validation","hooks"],"backgroundTag":"empty-required-field","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"}