affaan-m/ECC · error

Unknown install module

Error message

Unknown install module: ${moduleId}

What it means

During recursive dependency resolution, each requested module ID is looked up in manifests.modulesById. If a module ID (from the profile, explicit includes, or a dependency edge) has no manifest entry, resolveModule throws naming the unknown ID. This catches both bad user input and broken dependency references inside the manifest.

Solutions

1. Correct the module ID against the modules defined in manifests/install-modules.json
2. If the ID comes from a manifest dependency, fix the manifest entry (check for renamed modules)
3. Regenerate/sync the manifests (npm run catalog:sync) if they are stale
4. Remove the stale module reference from includes, profiles, or components

Example fix

// before
resolveInstallPlan({ profileId: 'standard', includeModuleIds: ['skills/tdd'] })
// after
resolveInstallPlan({ profileId: 'standard', includeModuleIds: ['skills/tdd-workflow'] })

const manifests = loadInstallManifests();
const unknown = (options.includeModuleIds ?? []).filter(id => !manifests.modulesById.get(id));
if (unknown.length) throw new Error(`unknown module(s): ${unknown.join(', ')}`);

function isKnownModule(id, manifests) {
  return typeof id === 'string' && manifests.modulesById.has(id);
}

try {
  const plan = resolveInstallPlan(options);
} catch (err) {
  if (err.message.startsWith('Unknown install module:')) {
    console.error(`${err.message} — check manifests/install-modules.json`); process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: resolveInstallPlan({ includeModuleIds: ['skills/nonexistent'] }) or a manifest profile/component/dependency referencing a module ID that is missing from manifests/install-modules.json.

Common situations: Typo in a module ID passed on the CLI, a hand-edited manifest that added a dependency on a removed module, or a version mismatch where a component references modules no longer defined.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• A normalized install request is required
• assets must be a nonempty list
• Circular install dependency detected at
• Duplicate asset id
• Each asset must be an object

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

Appendix: source

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

  }

  if (effectiveRequestedIds.length === 0) {
    throw new Error('Selection excludes every requested install module');
  }

  const selectedIds = new Set();
  const skippedTargetIds = new Set();
  const excludedIds = new Set([
    ...excludedModuleIds,
    ...targetDefaultExclusions.map(exclusion => exclusion.moduleId),
  ]);
  const visitingIds = new Set();
  const resolvedIds = new Set();

  function resolveModule(moduleId, dependencyOf, rootRequesterId) {
    const module = manifests.modulesById.get(moduleId);
    if (!module) {
      throw new Error(`Unknown install module: ${moduleId}`);
    }

    if (excludedModuleOwners.has(moduleId)) {
      if (dependencyOf) {
        const owners = excludedModuleOwners.get(moduleId) || [];
        throw new Error(
          `Module ${dependencyOf} depends on excluded module ${moduleId}${owners.length > 0 ? ` (excluded by ${owners.join(', ')})` : ''}`
        );
      }
      return;
    }

    const supportsTarget = !target
      || (
        readModuleTargetsOrThrow(module).includes(target)
        && (!targetAdapter || targetAdapter.supportsModule(module, targetPlanningInput))
      );

View on GitHub (pinned to 8321021c54)