affaan-m/ECC · error

Unknown install component

Error message

Unknown install component: ${componentId}

What it means

expandComponentIdsToModuleIds() resolves each component ID to its module list via manifests.componentsById. Any ID that does not resolve to a registered component aborts the whole expansion with this error, since a partial install plan would be unsafe.

Solutions

1. Validate every ID against listInstallComponents() output before building the plan
2. Correct or remove the unknown ID from the components list/config
3. After upgrading, re-sync component IDs (npm run catalog:sync) and update stale references
4. Wrap resolveInstallPlan() in try/catch and surface the offending ID to the user

Example fix

// before
resolveInstallPlan({ components: ['agents', 'hooks '] });
// after
resolveInstallPlan({ components: ['agents', 'hooks'] });

const knownIds = new Set(loadInstallManifests().componentsById.keys());
const bad = componentIds.filter(id => !knownIds.has(id));
if (bad.length) {
  throw new Error(`Unknown component IDs in plan: ${bad.join(', ')}`);
}

const allKnown = (ids, manifests) => ids.every(id => manifests.componentsById.has(id));

try {
  const plan = resolveInstallPlan(options);
} catch (err) {
  if (err.message.startsWith('Unknown install component')) {
    console.error(`Install plan references an invalid component: ${err.message}`);
    process.exitCode = 1;
  } else throw err;
}

When it happens

Trigger: Calling expandComponentIdsToModuleIds(['agents', 'typo-component'], manifests) — usually via resolveInstallPlan() or excludedModuleIds() with an invalid component ID in the install options/components list.

Common situations: An install config (e.g. install-modules.json component list or CLI --components flag) referencing a component that was renamed, deleted, or misspelled; or IDs copied from an older ECC version.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• Unknown install component
• Unknown install module
• Unknown install modules
• A managed install plan with operations is required.
• An install component ID is required

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

Appendix: source

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

  return {
    id: component.id,
    family: component.family,
    description: component.description,
    moduleIds,
    moduleCount: moduleIds.length,
    targets: intersectTargets(modules),
    modules,
  };
}

function expandComponentIdsToModuleIds(componentIds, manifests) {
  const expandedModuleIds = [];

  for (const componentId of dedupeStrings(componentIds)) {
    const component = manifests.componentsById.get(componentId);
    if (!component) {
      throw new Error(`Unknown install component: ${componentId}`);
    }
    expandedModuleIds.push(...component.modules);
  }

  return dedupeStrings(expandedModuleIds);
}

function getTargetDefaultProfileId(target, manifests) {
  const profileId = target ? TARGET_DEFAULT_PROFILE_IDS[target] : null;
  return profileId && manifests.profiles[profileId] ? profileId : null;
}

function getTargetDefaultExclusions(target, manifests) {
  const exclusions = target ? TARGET_DEFAULT_EXCLUSIONS[target] : null;
  if (!Array.isArray(exclusions)) {
    return [];
  }

View on GitHub (pinned to 8321021c54)