affaan-m/ECC · error

Unknown component family

Error message

Unknown component family: ${family}. Expected one of ${Object.keys(COMPONENT_FAMILY_PREFIXES).join(', ')}

What it means

listInstallComponents() validates the optional options.family against the known keys of COMPONENT_FAMILY_PREFIXES before filtering components. If the family string does not match any registered family, the library refuses to run rather than silently returning an empty list.

Solutions

1. Check the allowed family names with Object.keys(require('./scripts/lib/install-manifests').COMPONENT_FAMILY_PREFIXES) or the error message itself and use one exactly
2. Fix the typo / casing in the family value (families are lowercase, plural)
3. Call listInstallComponents() without the family option to list everything, then derive valid families from the returned components
4. If family comes from user input, validate it against COMPONENT_FAMILY_PREFIXES before calling

Example fix

// before
listInstallComponents({ family: 'skill' });
// after
listInstallComponents({ family: 'skills' });

const { COMPONENT_FAMILY_PREFIXES } = require('./scripts/lib/install-manifests');
if (family != null && !Object.hasOwn(COMPONENT_FAMILY_PREFIXES, family)) {
  throw new Error(`Invalid family '${family}'. Valid: ${Object.keys(COMPONENT_FAMILY_PREFIXES).join(', ')}`);
}

const isValidFamily = (f) => typeof f === 'string' && Object.hasOwn(COMPONENT_FAMILY_PREFIXES, f);

try {
  const comps = listInstallComponents({ family });
} catch (err) {
  if (err.message.startsWith('Unknown component family')) {
    console.error(err.message);
    process.exitCode = 1;
  } else throw err;
}

When it happens

Trigger: Calling listInstallComponents({ family: 'xyz' }) with a family name that is not a key of COMPONENT_FAMILY_PREFIXES — typos, renamed families after a version bump, or programmatic input from user config/CLI args.

Common situations: Typing 'skill' instead of 'skills', copying an option from outdated docs, wiring a CLI flag through without normalizing case, or a renamed/removed family in a newer ECC version.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Unknown install target
• An install component ID is required
• Install module has unsupported targets
• INVALID_HOOK_MODE
• INVALID_SCOPE

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/a20de917db74a108. Report an issue: GitHub.

Appendix: source

Thrown at scripts/lib/install-manifests.js:387

function listLegacyCompatibilityLanguages() {
  return Object.keys(LEGACY_LANGUAGE_ALIAS_TO_CANONICAL).sort();
}

function validateInstallModuleIds(moduleIds, options = {}) {
  const manifests = loadInstallManifests(options);
  const normalizedModuleIds = dedupeStrings(moduleIds);
  assertKnownModuleIds(normalizedModuleIds, manifests);
  return normalizedModuleIds;
}

function listInstallComponents(options = {}) {
  const manifests = loadInstallManifests(options);
  const family = options.family || null;
  const target = options.target || null;

  if (family && !Object.hasOwn(COMPONENT_FAMILY_PREFIXES, family)) {
    throw new Error(
      `Unknown component family: ${family}. Expected one of ${Object.keys(COMPONENT_FAMILY_PREFIXES).join(', ')}`
    );
  }

  if (target && !SUPPORTED_INSTALL_TARGETS.includes(target)) {
    throw new Error(
      `Unknown install target: ${target}. Expected one of ${SUPPORTED_INSTALL_TARGETS.join(', ')}`
    );
  }

  return manifests.components
    .filter(component => !family || component.family === family)
    .map(component => {
      const moduleIds = dedupeStrings(component.modules);
      const modules = moduleIds
        .map(moduleId => manifests.modulesById.get(moduleId))
        .filter(Boolean);
      const targets = intersectTargets(modules);

View on GitHub (pinned to 8321021c54)