affaan-m/ECC · error · Error

${flagName} requires a value

Error message

${flagName} requires a value

What it means

Thrown by readValue in platform-audit's arg parser when a flag that expects a value is either the last token on the line or is immediately followed by another `--` flag. It guards every value-taking option (--format, --root, --repo, --allow-untracked, --write, --max-open-prs, --max-open-issues, --max-dirty-files) so parseArgs never silently treats a flag name as a value.

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 01e15490f0)

Solutions

1. Supply the value immediately after the flag: `--format json`.
2. Use the `=` form which cannot trigger this: `--format=json`, `--root=/repo`.
3. Check that any shell variable used as a value is non-empty and quoted.

Example fix

# before
node scripts/platform-audit.js --root --repo owner/repo
# after
node scripts/platform-audit.js --root /path/to/repo --repo owner/repo
# or
node scripts/platform-audit.js --root=/path/to/repo --repo=owner/repo

// Validate a flag/value pair before the parser sees it
function ensureFlagHasValue(args, index, flagName) {
  const value = args[index + 1];
  if (!value || value.startsWith('--')) {
    throw new Error(`${flagName} requires a value`);
  }
  return value;
}

function isFlagValue(token) {
  return typeof token === 'string' && token.length > 0 && !token.startsWith('--');
}

try {
  parseArgs(process.argv);
} catch (err) {
  if (err.message.endsWith('requires a value')) {
    console.error(`${err.message}. Tip: use --flag=value form.`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Trailing flag with no value: `--format` at end of line; value that is itself a flag like `--root --repo x`; copy-paste that dropped the value; shell quoting that swallowed the value leaving the next flag adjacent.

Common situations: User edits a CI invocation and deletes a value; env var expansion produced empty between two flags; alias/wrapper script concatenates args incorrectly.

Related errors

• Invalid ${flagName}: ${value}
• Unknown argument: ${arg}
• Invalid format: ${parsed.format}. Use text, json, or markdow
• --write requires --json, --markdown, or --format json|markdo
• Unknown argument: ${arg}

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