denoland/deno · error · TypeError

ERR_INVALID_ARG_VALUE

ERR_INVALID_ARG_VALUE

Error message

The property 'options.${longOption}.short' must be a single character. Received ${inspected}

What it means

Config-time validation inside parseArgs: for each declared option that has a 'short', the value must already be a string (validateString) and then must be exactly one character; a longer or empty string throws ERR_INVALID_ARG_VALUE for options.<name>.short.

Source

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

  validateBoolean(returnTokens, "tokens");
  validateObject(options, "options");
  ArrayPrototypeForEach(
    ObjectEntries(options),
    ({ 0: longOption, 1: optionConfig }) => {
      validateObject(optionConfig, `options.${longOption}`);

      // type is required
      const optionType = objectGetOwn(optionConfig, "type");
      validateUnion(optionType, `options.${longOption}.type`, [
        "string",
        "boolean",
      ]);

      if (ObjectHasOwn(optionConfig, "short")) {
        const shortOption = optionConfig.short;
        validateString(shortOption, `options.${longOption}.short`);
        if (shortOption.length !== 1) {
          throw new ERR_INVALID_ARG_VALUE(
            `options.${longOption}.short`,
            shortOption,
            "must be a single character",
          );
        }
      }

      const multipleOption = objectGetOwn(optionConfig, "multiple");
      if (ObjectHasOwn(optionConfig, "multiple")) {
        validateBoolean(multipleOption, `options.${longOption}.multiple`);
      }

      const defaultValue = objectGetOwn(optionConfig, "default");
      if (defaultValue !== undefined) {
        let validator;
        switch (optionType) {
          case "string":
            validator = multipleOption ? validateStringArray : validateString;

View on GitHub (pinned to 9ad36f7a2c)

Solutions

1. Use exactly one character: short: 'l'
2. Omit short entirely when no short form is wanted
3. When generating configs, assert short.length === 1 before calling parseArgs

Example fix

// before
parseArgs({ options: { output: { type: 'string', short: 'output' } }, args: [] }); // throws

// after
parseArgs({ options: { output: { type: 'string', short: 'o' } }, args: [] });

for (const [name, o] of Object.entries(options)) {
  if (o.short !== undefined && o.short.length !== 1) {
    throw new Error(`options.${name}.short must be a single character`);
  }
}
const { values } = parseArgs({ options, args });

const validShort = (s) => s === undefined || (typeof s === 'string' && s.length === 1);

When it happens

Trigger: parseArgs({options: {log: {type: 'string', short: 'log'}}}); short: ''; programmatically generated configs where the long name is reused as the short.

Common situations: Copy-pasting the long name into the short field; config loaded from YAML/JSON with short: ['l'] (array) or 'vv'; generators that forget to truncate.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• ERR_PARSE_ARGS_INVALID_OPTION_VALUE
• ERR_PARSE_ARGS_UNKNOWN_OPTION
• ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL
• '{}' did not have a bin property with a string or non-empty
• '{}' did not have a bin entry for '{}'{}

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