affaan-m/ECC · error · Error

--locale can only be used with --target claude or --target c

Error message

--locale can only be used with --target claude or --target claude-project

What it means

Thrown by normalizeInstallRequest() when --locale is supplied together with a target other than 'claude' or 'claude-project'. Translation bundles are only wired into the Claude harness targets; cursor and antigravity targets have no locale installation path.

Source

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

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 || []),
  ]);
  const legacyLanguages = dedupeStrings(dedupeStrings([
    ...(Array.isArray(options.legacyLanguages) ? options.legacyLanguages : []),
    ...(Array.isArray(options.languages) ? options.languages : []),
  ]).map(language => language.toLowerCase()));
  const hasManifestBaseSelection = Boolean(profileId) || moduleIds.length > 0 || includeComponentIds.length > 0;

View on GitHub (pinned to 01e15490f0)

Solutions

Drop --locale when targeting cursor or antigravity.
Switch the target to claude or claude-project if you need the translation bundle.
Run two separate installs: one Claude-targeted with --locale, one Cursor-targeted without.

Example fix

# before
npx ecc install --target cursor --locale zh-CN
# after
npx ecc install --target cursor

Defensive patterns

Strategy: validation

Validate before calling

function localeTargetCompatible(target, locale) {
  if (!locale) return true;
  return target === 'claude' || target === 'claude-project';
}
// guard:
if (!localeTargetCompatible(options.target || 'claude', options.locale)) {
  throw new Error('--locale requires --target claude or --target claude-project');
}

Type guard

function supportsLocale(target) {
  return target === 'claude' || target === 'claude-project';
}

Try / catch

try {
  request = normalizeInstallRequest(options);
} catch (e) {
  if (/--locale can only be used with/.test(e.message)) {
    const { locale, ...rest } = options;
    request = normalizeInstallRequest(rest); // drop locale and retry
  } else throw e;
}

Prevention

Gate --locale in your wrapper on the target value before assembling the command.
Document the locale/target matrix for users mixing harnesses.
When looping over multiple targets, conditionally include --locale only for Claude targets.

When it happens

Trigger: Combining `--target cursor` or `--target antigravity` with `--locale zh-CN`.

Common situations: Reusing a Claude-targeted install command for Cursor; assuming locale applies to every harness.

Related errors

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