affaan-m/ECC · error · Error

requires a value

Error message

${flagName} requires a value

What it means

readValue is the platform-audit CLI's helper for consuming a flag's value: it looks at the next argv element and rejects it if missing or if it begins with '--' (i.e. the next thing is another flag, not a value). It throws '<flagName> requires a value' so the audit exits with a clear usage error instead of silently parsing a flag as a value.

Solutions

1. Supply the value right after the flag with a single space: `--format json`, `--output audit.md`.
2. If the value may start with '--' (e.g. `--label --keep`), use `=` syntax if supported or quote/reorder so the parser sees a non-flag token.
3. Check shell variables for empty expansion before running: `: "${AUDIT_OUT:?output path required}"`.
4. Run with no flags to see usage text listing which flags take values.

Example fix

# before (value missing / looks like a flag)
node scripts/platform-audit.js --format --json

# after
node scripts/platform-audit.js --format json

# ensure value-bearing flags have a non-flag token after them
[[ -n "${OUTPUT:-}" && "${OUTPUT:0:2}" != '--' ]] || { echo '--output requires a value'; exit 2; }

try {
  const parsed = parseArgs(process.argv);
} catch (err) {
  if (/requires a value/.test(err.message)) {
    console.error(`${err.message}\nUsage: node scripts/platform-audit.js --output <path> --format json`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Running `node scripts/platform-audit.js --output` (nothing after the flag), `--format` followed immediately by another flag like `--json`, or a value that legitimately starts with '--'.

Common situations: Truncated command from docs where the value placeholder was dropped; a boolean-style habit (`--format --json`) from tools where flags are self-contained; environment-substituted values that expanded to empty (`--output $AUDIT_OUT` with the var unset) so the next token is another flag.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• Invalid
• Unknown argument
• requires a value.
• does not accept positional arguments.
• --exit-code with --watch requires --watch-count so the…

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

Appendix: source

Thrown at scripts/platform-audit.js:53

    '  --markdown                 Alias for --format markdown',
    '  --write <path>             Write json or markdown output to a file',
    '  --root <dir>               Repository root to inspect (default: cwd)',
    '  --repo <owner/repo>        GitHub repo to inspect; repeatable',
    '  --skip-github              Skip live GitHub queue/discussion checks',
    '  --max-open-prs <n>         Fail when open PR count is above n (default: 20)',
    '  --max-open-issues <n>      Fail when open issue count is above n (default: 20)',
    '  --max-dirty-files <n>      Fail when blocking dirty file count is above n (default: 0)',
    '  --allow-untracked <path>   Ignore untracked files under path; repeatable',
    '  --use-env-github-token     Keep GITHUB_TOKEN when invoking gh',
    '  --exit-code                Return 2 when the audit is not ready',
    '  --help, -h                 Show this help',
  ].join('\n'));
}

function readValue(args, index, flagName) {
  const value = args[index + 1];
  if (!value || value.startsWith('--')) {
    throw new Error(`${flagName} requires a value`);
  }
  return value;
}

function parseIntegerFlag(value, flagName) {
  const parsed = Number.parseInt(value, 10);
  if (!Number.isFinite(parsed) || parsed < 0) {
    throw new Error(`Invalid ${flagName}: ${value}`);
  }
  return parsed;
}

function parseArgs(argv) {
  const args = argv.slice(2);
  const parsed = {
    allowUntracked: [],
    exitCode: false,
    format: 'text',

View on GitHub (pinned to 8321021c54)