affaan-m/ECC · error · Error

Unsupported locale: "${locale}". Supported locales: ${listSu

Error message

Unsupported locale: "${locale}". Supported locales: ${listSupportedLocales().join(', ')}

What it means

Thrown by normalizeInstallRequest() when a locale was supplied but is absent from the LOCALE_ALIAS_TO_COMPONENT_ID map. The map is the authoritative allowlist; anything else is rejected before any install planning happens.

Source

Thrown at scripts/lib/install/request.js:99

    }
  }

  return parsed;
}

function normalizeInstallRequest(options = {}) {
  const config = options.config && typeof options.config === 'object'
    ? options.config
    : null;
  const profileId = options.profileId || config?.profileId || null;
  const target = options.target || config?.target || 'claude';
  const moduleIds = validateInstallModuleIds(
    dedupeStrings([...(config?.moduleIds || []), ...(options.moduleIds || [])])
  );
  const locale = options.locale || config?.locale || null;
  const localeComponentId = locale ? LOCALE_ALIAS_TO_COMPONENT_ID[locale] : null;
  if (locale && !localeComponentId) {
    throw new Error(
      `Unsupported locale: "${locale}". Supported locales: ${listSupportedLocales().join(', ')}`
    );
  }
  if (locale && target !== 'claude' && target !== 'claude-project') {
    throw new Error('--locale can only be used with --target claude or --target claude-project');
  }
  const requestedIncludeComponentIds = dedupeStrings([
    ...(config?.includeComponentIds || []),
    ...(options.includeComponentIds || []),
  ]);
  const includeComponentIds = dedupeStrings([
    ...requestedIncludeComponentIds,
    ...(localeComponentId ? [localeComponentId] : []),
  ]);
  const excludeComponentIds = dedupeStrings([
    ...(config?.excludeComponentIds || []),
    ...(options.excludeComponentIds || []),
  ]);

View on GitHub (pinned to 01e15490f0)

Solutions

Call listSupportedLocales() (or check the install-manifests module) to see the exact accepted values for your ECC version.
Use the exact alias string the map expects (commonly hyphenated forms like zh-CN, zh-TW, ja-JP).
If you need an unavailable locale, contribute a translation rather than passing the unsupported code.

Example fix

# before
npx ecc install --locale fr --target claude
# after
npx ecc install --locale zh-CN --target claude

Defensive patterns

Strategy: validation

Validate before calling

const { listSupportedLocales, LOCALE_ALIAS_TO_COMPONENT_ID } = require('../install-manifests');
function isSupportedLocale(locale) {
  return Boolean(locale) && Object.prototype.hasOwnProperty.call(LOCALE_ALIAS_TO_COMPONENT_ID, locale);
}
// before calling normalizeInstallRequest:
if (options.locale && !isSupportedLocale(options.locale)) {
  throw new Error(`Locale '${options.locale}' is not supported. Supported: ${listSupportedLocales().join(', ')}`);
}

Type guard

function isSupportedLocale(locale, aliasMap) {
  return typeof locale === 'string' && Object.prototype.hasOwnProperty.call(aliasMap, locale);
}

Try / catch

try {
  request = normalizeInstallRequest(options);
} catch (e) {
  if (/^Unsupported locale:/.test(e.message)) {
    const supported = listSupportedLocales();
    if (!options.locale && options.config?.locale) options.config.locale = supported[0];
    request = normalizeInstallRequest({ ...options, locale: supported.includes(options.locale) ? options.locale : null });
  } else throw e;
}

Prevention

Always source the locale allowlist from listSupportedLocales() rather than hardcoding it.
Use exact hyphenated forms (zh-CN, not zh_CN or ZH-cn).
In UI dropdowns, populate options from the same function so users cannot pick an unsupported value.

When it happens

Trigger: Passing `--locale fr` (French not shipped), `--locale en` (English is the default, not a translation), or a malformed value like `--locale zh_cn` (underscore vs hyphen).

Common situations: Assuming a locale exists because the language is common; using an underscore separator; copy-pasting an IETF tag that ECC does not alias.

Related errors

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