affaan-m/ECC · error · Error

Unknown argument

Error message

Unknown argument: ${arg}

What it means

parseArgs classifies each token: --help, --json, VALUE_FLAGS, or a non-dash positional. Any remaining token starting with '-' is an unrecognized flag and throws 'Unknown argument: <arg>'. This is the top-level flag allowlist, distinct from assignOption's unknown-flag error (676).

Solutions

1. Remove or correct the unsupported flag; check `--help` output for the accepted set
2. Replace short flags with the long forms the script defines
3. Verify you're running the intended script — flag sets differ across scripts/ files
4. Update the repo if a documented flag is missing from your checkout

Example fix

// before
node scripts/work-items.js list --verbose
// after
node scripts/work-items.js list

const flags = process.argv.slice(2).filter(a => a.startsWith('-'));
const POSITIONALS_OK = true; // non-dash tokens are fine
const unknownFlags = flags.filter(a => a !== '--help' && a !== '--json' && !VALUE_FLAGS.has(a));
if (unknownFlags.length > 0) throw new Error(`Unknown argument(s): ${unknownFlags.join(', ')}`);

function isRecognizedToken(arg) {
  return !arg.startsWith('-') || arg === '--help' || arg === '--json' || VALUE_FLAGS.has(arg);
}

try {
  const options = parseArgs(process.argv);
} catch (err) {
  if (err.message.startsWith('Unknown argument:')) {
    console.error(`${err.message}. Short flags are not supported; use long forms.`);
    process.exit(2);
  }
  throw err;
}

When it happens

Trigger: Passing an unsupported dash-flag like `node scripts/work-items.js list --verbose` or `--limit 5`, or mistyped supported flags (e.g. `--jsoin`), or single-dash short forms like `-t` that aren't registered.

Common situations: Assuming Unix-style short flags exist; flags copied from other tools' CLIs; running an older version of the script that lacks a newer flag; shell aliases expanding into unexpected tokens.

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

• Unknown argument
• Unknown argument
• decisions does not accept a session ID when --all is set
• Invalid value: expected a path
• must use non-empty key=value form

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

Appendix: source

Thrown at scripts/work-items.js:114

  }

  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (arg === '--help' || arg === '-h') {
      parsed.help = true;
    } else if (arg === '--json') {
      parsed.json = true;
    } else if (VALUE_FLAGS.has(arg)) {
      const value = args[index + 1];
      if (!value || value.startsWith('--')) {
        throw new Error(`Missing value for ${arg}`);
      }
      assignOption(parsed, arg, value);
      index += 1;
    } else if (!arg.startsWith('-')) {
      parsed.positionals.push(arg);
    } else {
      throw new Error(`Unknown argument: ${arg}`);
    }
  }

  return parsed;
}

function parseMetadataJson(value) {
  if (value === undefined || value === null) {
    return null;
  }

  try {
    return JSON.parse(value);
  } catch (error) {
    throw new Error(`Invalid --metadata-json: ${error.message}`);
  }
}

View on GitHub (pinned to 8321021c54)