affaan-m/ECC · error · Error

Unknown argument: ${arg}

Error message

Unknown argument: ${arg}

What it means

Thrown by scripts/status.js parseArgs when an argv token is not one of the recognized flags: --db, --json, --markdown, --exit-code, --write, --limit, --help, or -h. The parser is a strict allowlist with no pass-through for unknown options, so any unlisted flag aborts before the SQLite state store is opened. This is a fail-fast guard so malformed invocations surface immediately instead of silently producing partial status output.

Source

Thrown at scripts/status.js:54

    if (arg === '--db') {
      parsed.dbPath = args[index + 1] || null;
      index += 1;
    } else if (arg === '--json') {
      parsed.json = true;
    } else if (arg === '--markdown') {
      parsed.markdown = true;
    } else if (arg === '--exit-code') {
      parsed.exitCode = true;
    } else if (arg === '--write') {
      parsed.writePath = args[index + 1] || null;
      index += 1;
    } else if (arg === '--limit') {
      parsed.limit = args[index + 1] || null;
      index += 1;
    } else if (arg === '--help' || arg === '-h') {
      parsed.help = true;
    } else {
      throw new Error(`Unknown argument: ${arg}`);
    }
  }

  if (parsed.json && parsed.markdown) {
    throw new Error('Choose only one output format: --json or --markdown');
  }

  if (args.includes('--db') && !parsed.dbPath) {
    throw new Error('Missing value for --db');
  }

  if (args.includes('--write') && !parsed.writePath) {
    throw new Error('Missing value for --write');
  }

  if (args.includes('--limit') && !parsed.limit) {
    throw new Error('Missing value for --limit');
  }

View on GitHub (pinned to 01e15490f0)

Solutions

1. Run `node scripts/status.js --help` to list the valid flags and compare against the failing invocation.
2. Check the exact spelling of the flag reported in the error message and correct the typo.
3. If a wrapper script passes the flag, update it to the current flag name or remove the unsupported option.
4. Confirm you are on the ECC version whose flag set you expect (the parser only accepts the eight flags listed in showHelp).

Example fix

// before
node scripts/status.js --output report.txt

// after
node scripts/status.js --json --write report.txt

// Validate status.js args before spawning the script
const STATUS_FLAGS = new Set(['--db', '--json', '--markdown', '--exit-code', '--write', '--limit', '--help', '-h']);
const VALUE_FLAGS = new Set(['--db', '--write', '--limit']);

function validateStatusArgs(argv) {
  for (let i = 0; i < argv.length; i++) {
    const tok = argv[i];
    if (tok.startsWith('-') && !STATUS_FLAGS.has(tok)) {
      throw new Error(`Unsupported status.js flag: ${tok}`);
    }
    if (VALUE_FLAGS.has(tok) && (i + 1 >= argv.length || !argv[i + 1])) {
      throw new Error(`Flag ${tok} needs a value`);
    }
    if (VALUE_FLAGS.has(tok)) i += 1; // skip the value
  }
}
// validateStatusArgs(['--json', '--write', '/tmp/out.json']); // ok
// validateStatusArgs(['--verbose']); // throws early

// When invoking status.js programmatically, capture stderr + exit code
const { spawnSync } = require('child_process');
const r = spawnSync(process.execPath, ['scripts/status.js', ...userArgs], { encoding: 'utf8' });
if (r.status !== 0) {
  const msg = (r.stderr || '').trim();
  if (msg.startsWith('Error: Unknown argument')) {
    // surface a friendly hint to the caller and fall back to --help
    console.error('status.js rejected a flag. Run with --help for the valid set.');
  }
  throw new Error(`status.js failed (${r.status}): ${msg}`);
}

When it happens

Trigger: Passing any flag outside the recognized set, e.g. `node scripts/status.js --verbose`, `--output report.txt`, `-v`, or `--format json` (the correct flag is --json). Also triggered by a flag that was renamed or removed in a newer ECC version while a wrapper script still passes the old spelling.

Common situations: Wrapper scripts or CI jobs hard-coding flags from an older ECC release; typos like `--josn` or `--wrtie`; copy-pasting a flag from a different CLI (e.g. --format from another tool) into an ECC status command; shell aliases that append extra flags.

Related errors

• ${label} must be a positive integer
• Unknown install target: ${parsed.target}. Expected one of ${
• Invalid ${flagName}: ${value}
• Invalid format: ${parsed.format}. Use text, json, or markdow
• --write requires --json, --markdown, or --format json|markdo

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