What causes "A normalized install request is required" in affaan-m/ECC?

Run the input through normalizeInstallRequest() first and pass its return value.

affaan-m/ECC · error · Error

A normalized install request is required

Error message

A normalized install request is required

What it means

Thrown by createInstallPlanFromRequest() when the request argument is null, undefined, or not an object. The function expects a request that has already been normalized by normalizeInstallRequest(); passing raw CLI args, an array, or a primitive is a programming error.

Source

Thrown at scripts/lib/install/runtime.js:11

'use strict';

const {
  createLegacyCompatInstallPlan,
  createLegacyInstallPlan,
  createManifestInstallPlan,
} = require('../install-executor');

function createInstallPlanFromRequest(request, options = {}) {
  if (!request || typeof request !== 'object') {
    throw new Error('A normalized install request is required');
  }

  if (request.mode === 'manifest') {
    return createManifestInstallPlan({
      target: request.target,
      profileId: request.profileId,
      moduleIds: request.moduleIds,
      includeComponentIds: request.includeComponentIds,
      excludeComponentIds: request.excludeComponentIds,
      projectRoot: options.projectRoot,
      homeDir: options.homeDir,
      sourceRoot: options.sourceRoot,
    });
  }

  if (request.mode === 'legacy-compat') {
    return createLegacyCompatInstallPlan({
      target: request.target,

View on GitHub (pinned to 01e15490f0)

Solutions

Run the input through normalizeInstallRequest() first and pass its return value.
If you already normalized, check that the variable is not shadowed or reassigned to null before the call.
Add a type guard at the call site to fail earlier with a clearer message.

Example fix

// before
const plan = createInstallPlanFromRequest(argv[2]);
// after
const request = normalizeInstallRequest(parseInstallArgs(argv));
const plan = createInstallPlanFromRequest(request, { projectRoot });

Defensive patterns

Strategy: type-guard

Validate before calling

function isNormalizedRequest(req) {
  return Boolean(req)
    && typeof req === 'object'
    && !Array.isArray(req)
    && ['manifest','legacy-compat','legacy'].includes(req.mode)
    && typeof req.target === 'string';
}
if (!isNormalizedRequest(request)) {
  throw new Error('createInstallPlanFromRequest requires output of normalizeInstallRequest().');
}

Type guard

function isInstallRequest(value) {
  return value != null
    && typeof value === 'object'
    && !Array.isArray(value)
    && typeof value.mode === 'string'
    && typeof value.target === 'string';
}

Try / catch

try {
  plan = createInstallPlanFromRequest(request, options);
} catch (e) {
  if (/normalized install request is required/.test(e.message)) {
    request = normalizeInstallRequest(parseInstallArgs(process.argv));
    plan = createInstallPlanFromRequest(request, options);
  } else throw e;
}

Prevention

Always pipe parseInstallArgs -> normalizeInstallRequest -> createInstallPlanFromRequest; never skip a stage.
Add a runtime type guard at module entry in integrations.
Unit-test the full pipeline so a null request is caught early.

When it happens

Trigger: Calling createInstallPlanFromRequest(null), createInstallPlanFromRequest(undefined), createInstallPlanFromRequest('manifest'), or createInstallPlanFromRequest([request]) from a custom integration that bypasses normalizeInstallRequest().

Common situations: A wrapper script that forgets to call normalizeInstallRequest(); conditional code that passes request only in some branches; a refactor that changed the call site without updating the argument.

Related errors

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