{"record":{"id":"1e8e468f3927ca45","repo":"denoland/deno","slug":"err-parse-args-unexpected-positional","errorCode":"ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL","errorMessage":"Unexpected argument '${x}'. This command does not take positional arguments","messagePattern":"Unexpected argument '(.+?)'\\. This command does not take positional arguments","errorType":"error_code","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"ext/node/polyfills/internal/util/parse_args/parse_args.js","lineNumber":447,"sourceCode":"          );\n        } else {\n          value = false;\n        }\n      }\n\n      const checkToken = {\n        ...token,\n        name: name, // Use the processed name (without --no- prefix if applicable)\n      };\n\n      if (strict) {\n        checkOptionUsage(parseConfig, checkToken);\n        checkOptionLikeValue(checkToken);\n      }\n      storeOption(name, value, options, result.values);\n    } else if (token.kind === \"positional\") {\n      if (!allowPositionals) {\n        throw new ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL(token.value);\n      }\n      ArrayPrototypePush(result.positionals, token.value);\n    }\n  });\n\n  // Phase 3: fill in default values for missing args\n  ArrayPrototypeForEach(\n    ObjectEntries(options),\n    ({ 0: longOption, 1: optionConfig }) => {\n      const mustSetDefault = useDefaultValueOption(\n        longOption,\n        optionConfig,\n        result.values,\n      );\n      if (mustSetDefault) {\n        storeDefaultOption(\n          longOption,\n          objectGetOwn(optionConfig, \"default\"),","sourceCodeStart":429,"sourceCodeEnd":465,"githubUrl":"https://github.com/denoland/deno/blob/9ad36f7a2cce60488e6ec52283efb32efddaf93a/ext/node/polyfills/internal/util/parse_args/parse_args.js#L429-L465","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nconst { values } = parseArgs({ options: { minify: { type: 'boolean' } }, args: ['--minify', 'app.js'] }); // throws\n\n// after\nconst { values, positionals } = parseArgs({ allowPositionals: true, options: { minify: { type: 'boolean' } }, args: ['--minify', 'app.js'] }); // positionals[0] === 'app.js'","handlingStrategy":"validation","validationCode":"const expectsOperands = args.some((a) => !a.startsWith('-'));\nconst parsed = parseArgs({ allowPositionals: expectsOperands, options, args });","typeGuard":null,"tryCatchPattern":"try {\n  const { values } = parseArgs({ options, args });\n} catch (err) {\n  if (err.code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL') {\n    console.error(`This command takes no positional arguments\\nUsage: myapp [--flag]`);\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["parse-args","cli","node-compat","positional-args"],"backgroundTag":"unexpected-positional-argument","analyzedSha":"9ad36f7a2cce60488e6ec52283efb32efddaf93a","analyzedAt":"2026-08-20T13:07:44.778Z","contentChangedAt":"2026-08-20T13:07:44.778Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}