affaan-m/ECC · error · Error

Unknown component family: ${family}. Expected one of ${Objec

Error message

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

What it means

listInstallComponents accepts an optional `family` filter. If provided, it must be one of the keys in COMPONENT_FAMILY_PREFIXES (baseline, language, framework, capability, agent, skill, locale). Any other value is rejected up front with the valid set listed.

Source

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

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 01e15490f0)

Solutions

Compare the supplied family against the list in the error message (baseline, language, framework, capability, agent, skill, locale).
Fix the typo / casing.
If you genuinely need a new family, upgrade the installer so COMPONENT_FAMILY_PREFIXES includes it.
Drop the family filter to list components across all families.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

const KNOWN_FAMILIES = new Set(['baseline','language','framework','capability','agent','skill','locale']);
function isKnownFamily(f) { return f == null || KNOWN_FAMILIES.has(f); }
// before listInstallComponents: assert isKnownFamily(opts.family)

Type guard

function isSupportedComponentFamily(family) {
  return family == null || KNOWN_FAMILIES.has(family);
}

Try / catch

try {
  listInstallComponents({ family });
} catch (err) {
  if (err.message.startsWith('Unknown component family')) {
    // fall back to listing all families, or fix the typo
  } else throw err;
}

Prevention

Forward only validated family strings from CLI input.
Document the valid family set next to the --family flag.
Add a unit test that rejects each invalid family in the error message.
Re-validate after upgrading since the family set may grow.

When it happens

Trigger: Calling listInstallComponents({ family: '...' }) with an unknown family — typo ('Skils'), wrong category ('themes'), or a forward reference to a family added in a newer version. Triggered before any component filtering runs.

Common situations: CLI flag typo (--family themse); programmatic caller hard-coded an outdated family name; user guessed a family not in the catalog; manifest added a new family but the running installer predates it.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/a20de917db74a108. Report an issue: GitHub.