affaan-m/ECC · error

Invalid --scope value

Error message

Invalid --scope value: ${options.scope}

What it means

parseArgs validates --scope against the VALID_SCOPES set (user, project, local per the help text) and throws this when the value is not one of them. The scope determines where the plugin configuration is installed, so only the three enumerated destinations are accepted.

Solutions

1. Use one of the exact values: user, project, or local.
2. Fix casing — the check is case-sensitive, so lowercase the value.
3. Run `ecc setup --help` to see the 'Install scopes' section listing valid values.

Example fix

// before
npm run setup -- --mode claude-plugin --scope global

// after
npm run setup -- --mode claude-plugin --scope user

const VALID_SCOPES = new Set(['user', 'project', 'local']);
if (scopeArg !== undefined && !VALID_SCOPES.has(scopeArg)) {
  throw new Error(`Invalid --scope value: ${scopeArg}`);
}

const isValidScope = (v) => ['user', 'project', 'local'].includes(v);

try {
  await runSetup(rawArgs);
} catch (err) {
  if (/^Invalid --scope value: /.test(err.message)) {
    console.error(`${err.message}. Use one of: user, project, local.`);
    process.exitCode = 2;
  } else throw err;
}

When it happens

Trigger: Running `ecc setup --scope global`, `ecc setup --scope repo`, `ecc setup --scope Project`, or any misspelled/unknown scope string.

Common situations: Using synonyms from other tools ('global', 'workspace'); case-sensitivity mistakes ('User'); typos ('projekt'); scripts built from outdated documentation listing different scope names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• --host-provider must be anthropic, openai, or unknown
• Invalid --action value
• Invalid format: . Use text, json, or markdown.
• Invalid format: . Use text, json, or markdown.
• Invalid format: . Use text, json, or markdown.

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

Appendix: source

Thrown at scripts/setup.js:107

      options.yes = true;
    } else if (argument === '--dry-run') {
      options.dryRun = true;
    } else if (argument === '--move-scope') {
      options.moveScope = true;
    } else if (argument === '--json') {
      options.json = true;
    } else if (argument === '--help' || argument === '-h') {
      options.help = true;
    } else {
      throw new Error(`Unknown argument: ${argument}`);
    }
  }

  if (options.mode !== undefined && options.mode !== MODE) {
    throw new Error(`Invalid setup mode: ${options.mode}. This command currently supports ${MODE}.`);
  }
  if (options.scope !== undefined && !VALID_SCOPES.has(options.scope)) {
    throw new Error(`Invalid --scope value: ${options.scope}`);
  }
  if (options.hooks !== undefined && !VALID_HOOK_MODES.has(options.hooks)) {
    throw new Error(`Invalid --hooks value: ${options.hooks}`);
  }
  if (options.moveScope && options.scope === undefined) {
    throw new Error('--move-scope requires an explicit --scope destination.');
  }
  return options;
}

function questionWithCancellation(terminal, prompt) {
  return new Promise((resolve, reject) => {
    let settled = false;
    const finish = callback => value => {
      if (settled) return;
      settled = true;
      terminal.removeListener('close', onClose);
      callback(value);

View on GitHub (pinned to 8321021c54)