{"record":{"id":"24bd62b8403ae185","repo":"denoland/deno","slug":"err-parse-args-unknown-option","errorCode":"ERR_PARSE_ARGS_UNKNOWN_OPTION","errorMessage":"Unknown option '${option}'. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- ${JSONStringify(option)}","messagePattern":"Unknown option '(.+?)'\\. To specify a positional argument starting with a '-', place it at the end of the command after '--', as in '-- (.+?)","errorType":"exception","errorClass":"NodeTypeError","httpStatus":null,"severity":"error","filePath":"ext/node/polyfills/internal/util/parse_args/parse_args.js","lineNumber":100,"sourceCode":"    // Only show short example if user used short option.\n    const example = StringPrototypeStartsWith(token.rawName, \"--\")\n      ? `'${token.rawName}=-XYZ'`\n      : `'--${token.name}=-XYZ' or '${token.rawName}-XYZ'`;\n    const errorMessage = `Option '${token.rawName}' argument is ambiguous.\nDid you forget to specify the option argument for '${token.rawName}'?\nTo specify an option argument starting with a dash use ${example}.`;\n    throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(errorMessage);\n  }\n}\n\n/**\n * In strict mode, throw for usage errors.\n * @param {object} config - from config passed to parseArgs\n * @param {object} token - from tokens as available from parseArgs\n */\nfunction checkOptionUsage(config, token) {\n  if (!ObjectHasOwn(config.options, token.name)) {\n    throw new ERR_PARSE_ARGS_UNKNOWN_OPTION(\n      token.rawName,\n      config.allowPositionals,\n    );\n  }\n\n  const short = optionsGetOwn(config.options, token.name, \"short\");\n  const shortAndLong = `${short ? `-${short}, ` : \"\"}--${token.name}`;\n  const type = optionsGetOwn(config.options, token.name, \"type\");\n  if (type === \"string\" && typeof token.value !== \"string\") {\n    throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(\n      `Option '${shortAndLong} <value>' argument missing`,\n    );\n  }\n  // (Idiomatic test for undefined||null, expecting undefined.)\n  if (type === \"boolean\" && token.value != null) {\n    throw new ERR_PARSE_ARGS_INVALID_OPTION_VALUE(\n      `Option '${shortAndLong}' does not take an argument`,\n    );","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/denoland/deno/blob/9ad36f7a2cce60488e6ec52283efb32efddaf93a/ext/node/polyfills/internal/util/parse_args/parse_args.js#L82-L118","documentation":"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.","triggerScenarios":"parseArgs({options: {verbose: {type: 'boolean'}}}) with args ['--verbos'] (typo) or ['--silent'] (undeclared); using -v without declaring short: 'v' on an option.","commonSituations":"Users passing --help/--version the tool never declared; renamed flags while muscle memory keeps the old name; shorts assumed to work automatically.","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 --"],"exampleFix":"// before\nconst { values } = parseArgs({ options: {}, args: ['--color'] }); // throws\n\n// after\nconst { values } = parseArgs({ options: { color: { type: 'boolean' } }, args: ['--color'] });","handlingStrategy":"try-catch","validationCode":"const known = new Set(Object.entries(options).flatMap(([k, o]) => [`--${k}`, ...(o.short ? [`-${o.short}`] : [])]));\nconst unknown = args.filter((a) => a.startsWith('--') && !a.includes('=') && !known.has(a));\nif (unknown.length) console.error(`Unknown option(s): ${unknown.join(', ')}`);","typeGuard":null,"tryCatchPattern":"try {\n  const { values } = parseArgs({ options, args, strict: true });\n} catch (err) {\n  if (err.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {\n    console.error(`${err.message}\\nUsage: myapp [--color] [--file <path>]`);\n    process.exit(2);\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["parse-args","cli","node-compat","unknown-option"],"backgroundTag":"unknown-cli-option","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"}