affaan-m/ECC · error · Error

Unknown argument

Error message

Unknown argument: ${arg}

What it means

parseArgs in scripts/harness-adapter-compliance.js accepts a fixed set of flags; any argument that does not match one of the known prefixes hits the final throw `Unknown argument: <arg>`. The parser is strict: it refuses unknown flags rather than ignoring them.

Solutions

1. Remove or correct the offending argument; run the script with no args/--help to list supported flags.
2. Match the exact prefix the parser checks (e.g. --root= with equals sign, not --root <value>).
3. Compare against a working invocation of the same script (CI config, package.json scripts, docs).
4. If you need a new flag, extend parseArgs rather than hoping it is accepted.

Example fix

// before
node scripts/harness-adapter-compliance.js --root ./sub --verbose

// after
node scripts/harness-adapter-compliance.js --root=./sub

const KNOWN = /^--(root=|format=|json$|text$|markdown$)/; // adjust to actual flag list
const bad = argv.filter((a) => a.startsWith('--') && !KNOWN.test(a));
if (bad.length) throw new Error(`Unknown argument(s): ${bad.join(', ')}`);

const isKnownFlag = (arg) =>
  arg.startsWith('--root=') || arg.startsWith('--format=') || arg === '--help';

try {
  const parsed = parseArgs(process.argv);
} catch (e) {
  if (e.message.startsWith('Unknown argument:')) {
    console.error(e.message + ' — see --help for supported flags');
    process.exit(2);
  }
  throw e;
}

When it happens

Trigger: Passing a flag the script does not know (e.g. --verbose, --out=file), using a space-separated value after a flag that only supports = syntax, or misspelling a supported flag (--rooot=...).

Common situations: Reusing command lines from other ECC scripts with different flag sets; shell aliases appending extra flags; typos in flag names; assuming an older version supported a flag that was removed.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• must be a positive integer
• Invalid
• Unknown argument
• all overlays must be readable local files
• all takes must be readable local files

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

Appendix: source

Thrown at scripts/harness-adapter-compliance.js:56

    }

    if (arg.startsWith('--format=')) {
      parsed.format = arg.slice('--format='.length).toLowerCase();
      continue;
    }

    if (arg === '--root') {
      parsed.root = path.resolve(args[index + 1] || process.cwd());
      index += 1;
      continue;
    }

    if (arg.startsWith('--root=')) {
      parsed.root = path.resolve(arg.slice('--root='.length));
      continue;
    }

    throw new Error(`Unknown argument: ${arg}`);
  }

  if (!['text', 'json', 'markdown'].includes(parsed.format)) {
    throw new Error(`Invalid format: ${parsed.format}. Use text, json, or markdown.`);
  }

  parsed.root = path.resolve(parsed.root);
  return parsed;
}

function printHelp() {
  console.log([
    'Usage: node scripts/harness-adapter-compliance.js [options]',
    '',
    'Validate or render the ECC harness adapter compliance scorecard.',
    '',
    'Options:',
    '  --check                 Fail if adapter records or docs are out of sync',

View on GitHub (pinned to 8321021c54)