denoland/deno · error · NodeTypeError

ERR_PARSE_ARGS_INVALID_OPTION_VALUE

ERR_PARSE_ARGS_INVALID_OPTION_VALUE

Error message

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}.

What it means

In strict mode (the default), util.parseArgs treats an option-like value that is not inline ('--file --bar') as a probable mistake: the developer likely forgot the argument for the previous option. It throws ERR_PARSE_ARGS_INVALID_OPTION_VALUE with a hint to use '=' inline syntax for dash-leading values.

Source

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

  // Normally first two arguments are executable and script, then CLI arguments
  return ArrayPrototypeSlice(proc.argv, 2);
}

/**
 * In strict mode, throw for possible usage errors like --foo --bar
 * @param {object} token - from tokens as available from parseArgs
 */
function checkOptionLikeValue(token) {
  if (!token.inlineValue && isOptionLikeValue(token.value)) {
    // 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}`;

View on GitHub (pinned to 9ad36f7a2c)

Solutions

Use inline assignment: --file=-verbose (or -f-verbose for short options)
Place dash-leading values after the '--' terminator or reorder args
If the form is legitimate for your tool, parse with strict: false (permissive mode)

Example fix

// before
parseArgs({ options: { file: { type: 'string' } }, args: ['--file', '--sort'] }); // throws

// after
parseArgs({ options: { file: { type: 'string' } }, args: ['--file=--sort'] }); // ok

Defensive patterns

Strategy: try-catch

Validate before calling

const looksOption = (v) => typeof v === 'string' && v.startsWith('-') && v !== '-';
// build args with inline values when a value may start with '-':
const args = [`--file=${userValue}`]; // not '--file', userValue

Try / catch

try {
  const { values } = parseArgs({ options, args });
} catch (err) {
  if (err.code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE') {
    console.error(`Usage error: ${err.message}`);
    process.exit(2);
  }
  throw err;
}

Prevention

Emit dash-leading values inline with '=' when generating args
Validate user input before forwarding to parseArgs
Document the '=' form for values that start with a dash

When it happens

Trigger: util.parseArgs({options: {file: {type: 'string'}}, args: ['--file', '--verbose']}); a dash-leading value like --rate -0.5 passed as a separate token; forwarding user tokens verbatim into parseArgs.

Common situations: CLIs that accept negative numbers or dash-prefixed patterns (--delimiter --) as option values; args built by joining arrays where the value slot received the next flag.

Related errors

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