denoland/deno · error · TypeError

ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL

ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL

Error message

Unexpected argument '${x}'. This command does not take positional arguments

What it means

By default parseArgs does not allow positional arguments: allowPositionals is false, so only declared option tokens are legal. Any bare non-option token (kind 'positional') throws ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL, telling the user this command takes no positionals.

Source

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

          );
        } else {
          value = false;
        }
      }

      const checkToken = {
        ...token,
        name: name, // Use the processed name (without --no- prefix if applicable)
      };

      if (strict) {
        checkOptionUsage(parseConfig, checkToken);
        checkOptionLikeValue(checkToken);
      }
      storeOption(name, value, options, result.values);
    } else if (token.kind === "positional") {
      if (!allowPositionals) {
        throw new ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL(token.value);
      }
      ArrayPrototypePush(result.positionals, token.value);
    }
  });

  // Phase 3: fill in default values for missing args
  ArrayPrototypeForEach(
    ObjectEntries(options),
    ({ 0: longOption, 1: optionConfig }) => {
      const mustSetDefault = useDefaultValueOption(
        longOption,
        optionConfig,
        result.values,
      );
      if (mustSetDefault) {
        storeDefaultOption(
          longOption,
          objectGetOwn(optionConfig, "default"),

View on GitHub (pinned to 9ad36f7a2c)

Solutions

Enable positionals: parseArgs({allowPositionals: true, ...}) and read result.positionals
Strip known operands from args before parsing
Catch this error deliberately and print usage when extra operands are invalid for the command

Example fix

// before
const { values } = parseArgs({ options: { minify: { type: 'boolean' } }, args: ['--minify', 'app.js'] }); // throws

// after
const { values, positionals } = parseArgs({ allowPositionals: true, options: { minify: { type: 'boolean' } }, args: ['--minify', 'app.js'] }); // positionals[0] === 'app.js'

Defensive patterns

Strategy: validation

Validate before calling

const expectsOperands = args.some((a) => !a.startsWith('-'));
const parsed = parseArgs({ allowPositionals: expectsOperands, options, args });

Try / catch

try {
  const { values } = parseArgs({ options, args });
} catch (err) {
  if (err.code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL') {
    console.error(`This command takes no positional arguments\nUsage: myapp [--flag]`);
    process.exit(2);
  }
  throw err;
}

Prevention

Pass allowPositionals: true whenever operands (files, subcommands) are expected
Keep positionals after the '--' terminator in docs and examples
Decide operand policy per subcommand, not globally

When it happens

Trigger: parseArgs({options: {minify: {type: 'boolean'}}, args: ['--minify', 'app.js']}) without allowPositionals; args arrays that contain a subcommand or filename; a positional accidentally starting with '-' before any '--' terminator.

Common situations: Adding parseArgs to an existing CLI that always accepted filenames; forgetting that allowPositionals must be opted into; tests passing raw argv including the script path.

Related errors

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