denoland/deno · error · NodeTypeError

ERR_PARSE_ARGS_UNKNOWN_OPTION

ERR_PARSE_ARGS_UNKNOWN_OPTION

Error message

Unknown option '${option}'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- ${JSONStringify(option)}

What it means

Strict-mode parseArgs rejects any option token whose name is not declared in the options config (long names and shorts). This is the main typo guard; the message also explains that a positional starting with '-' must come after '--'. Thrown from checkOptionUsage() when ObjectHasOwn(config.options, token.name) is false.

Source

Thrown at ext/node/polyfills/internal/util/parse_args/parse_args.js:100

    // Only show short example if user used short option.
    const example = StringPrototypeStartsWith(token.rawName, "--")
      ? `'${token.rawName}=-XYZ'`
      : `'--${token.name}=-XYZ' or '${token.rawName}-XYZ'`;
    const errorMessage = `Option '${token.rawName}' argument is ambiguous.
Did you forget to specify the option argument for '${token.rawName}'?
To specify an option argument starting with a dash use ${example}.`;
    throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(errorMessage);
  }
}

/**
 * In strict mode, throw for usage errors.
 * @param {object} config - from config passed to parseArgs
 * @param {object} token - from tokens as available from parseArgs
 */
function checkOptionUsage(config, token) {
  if (!ObjectHasOwn(config.options, token.name)) {
    throw new ERR_PARSE_ARGS_UNKNOWN_OPTION(
      token.rawName,
      config.allowPositionals,
    );
  }

  const short = optionsGetOwn(config.options, token.name, "short");
  const shortAndLong = `${short ? `-${short}, ` : ""}--${token.name}`;
  const type = optionsGetOwn(config.options, token.name, "type");
  if (type === "string" && typeof token.value !== "string") {
    throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(
      `Option '${shortAndLong} <value>' argument missing`,
    );
  }
  // (Idiomatic test for undefined||null, expecting undefined.)
  if (type === "boolean" && token.value != null) {
    throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(
      `Option '${shortAndLong}' does not take an argument`,
    );

View on GitHub (pinned to 9ad36f7a2c)

Solutions

Declare the option: options: {silent: {type: 'boolean'}}
Fix the typo, or register short: 'v' alongside the long name
For ad-hoc parsing set strict: false; for dash-leading operands enable allowPositionals and put them after --

Example fix

// before
const { values } = parseArgs({ options: {}, args: ['--color'] }); // throws

// after
const { values } = parseArgs({ options: { color: { type: 'boolean' } }, args: ['--color'] });

Defensive patterns

Strategy: try-catch

Validate before calling

const known = new Set(Object.entries(options).flatMap(([k, o]) => [`--${k}`, ...(o.short ? [`-${o.short}`] : [])]));
const unknown = args.filter((a) => a.startsWith('--') && !a.includes('=') && !known.has(a));
if (unknown.length) console.error(`Unknown option(s): ${unknown.join(', ')}`);

Try / catch

try {
  const { values } = parseArgs({ options, args, strict: true });
} catch (err) {
  if (err.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
    console.error(`${err.message}\nUsage: myapp [--color] [--file <path>]`);
    process.exit(2);
  }
  throw err;
}

Prevention

Declare every accepted flag, including --help and --version if supported
Keep option names in one shared constant used by both parser and docs
Print friendly usage on this error instead of a raw stack

When it happens

Trigger: parseArgs({options: {verbose: {type: 'boolean'}}}) with args ['--verbos'] (typo) or ['--silent'] (undeclared); using -v without declaring short: 'v' on an option.

Common situations: Users passing --help/--version the tool never declared; renamed flags while muscle memory keeps the old name; shorts assumed to work automatically.

Related errors

AI-assisted analysis of denoland/deno@9ad36f7a2c (2026-08-20). Data as JSON: /api/errors/24bd62b8403ae185. Report an issue: GitHub.