{"record":{"id":"8445e1aeedffbd51","repo":"jackwener/OpenCLI","slug":"argument-argdef-name-must-be-one-of-argdef","errorCode":null,"errorMessage":"Argument \"${argDef.name}\" must be one of: ${argDef.choices.join(', ')}. Received: \"${coercedVal}\"","messagePattern":"Argument \"(.+?)\" must be one of: (.+?)\\. Received: \"(.+?)\"","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"src/execution.ts","lineNumber":91,"sourceCode":"        if (argDef.type === 'int' && !Number.isInteger(num)) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be a valid integer. Received: \"${val}\"`);\n        }\n        result[argDef.name] = num;\n      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {\n        if (typeof val === 'string') {\n          const lower = val.toLowerCase();\n          if (lower === 'true' || lower === '1') result[argDef.name] = true;\n          else if (lower === 'false' || lower === '0') result[argDef.name] = false;\n          else throw new ArgumentError(`Argument \"${argDef.name}\" must be a boolean (true/false). Received: \"${val}\"`);\n        } else {\n          result[argDef.name] = Boolean(val);\n        }\n      }\n\n      const coercedVal = result[argDef.name];\n      if (argDef.choices && argDef.choices.length > 0) {\n        if (!argDef.choices.map(String).includes(String(coercedVal))) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be one of: ${argDef.choices.join(', ')}. Received: \"${coercedVal}\"`);\n        }\n      }\n    } else if (argDef.default !== undefined) {\n      result[argDef.name] = argDef.default;\n    }\n  }\n  return result;\n}\n\nasync function runCommand(\n  cmd: CliCommand,\n  page: IPage | null,\n  kwargs: CommandArgs,\n  debug: boolean,\n): Promise<unknown> {\n  const internal = cmd as InternalCliCommand;\n  if (internal._lazy && internal._modulePath) {\n    const modulePath = internal._modulePath;","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/execution.ts#L73-L109","documentation":"This ArgumentError is thrown by coerceAndValidateArgs when a CLI argument that declares a `choices` list receives a value not contained in that list (compared as strings). The library validates user-supplied argument values against the argument definition at dispatch time so invalid input fails fast before the command's func or pipeline runs. It is a user-input error, not a library bug.","triggerScenarios":"Calling a command (e.g. via kwargs/runTask/main -> coerceAndValidateArgs) with a value for an argument defined with `choices: [...]` where String(coercedVal) is not in argDef.choices.map(String). Examples: `--mode fast` when choices are ['slow','medium']; passing a numeric value whose string form doesn't match (e.g. 1 vs 'one'); typos or casing differences like 'Prod' vs 'prod'.","commonSituations":"Typos in CLI invocations or scripts; outdated scripts written against an older set of allowed choices that has since changed; users guessing valid values when autocomplete/help isn't consulted; casing or whitespace mismatches in environment-driven argument values.","solutions":["Change the argument value to one of the choices listed in the error message (they are echoed verbatim after 'must be one of:').","Check the exact casing/spelling of your value — the comparison is string-exact after coercion, so 'Prod' fails when choices are ['prod'].","Run the command's help (or inspect the adapter definition) to see the authoritative list of choices and whether the set changed in a newer version.","If the value should legitimately be allowed, update the command's argDef.choices in the adapter definition and re-register the command."],"exampleFix":"// before\nmycli deploy --env staging   // ArgumentError: Argument \"env\" must be one of: prod, dev. Received: \"staging\"\n\n// after\nmycli deploy --env prod","handlingStrategy":"validation","validationCode":"function validateChoices(argDef, value) {\n  if (argDef?.choices?.length && !argDef.choices.map(String).includes(String(value))) {\n    throw new Error(`\"${value}\" is not one of: ${argDef.choices.join(', ')}`);\n  }\n}\n// call before dispatch: validateChoices(cmd.args?.find(a => a.name === 'env'), kwargs.env)","typeGuard":"function isAllowedChoice(value, choices) {\n  return choices.map(String).includes(String(value));\n}","tryCatchPattern":null,"preventionTips":["Read the command's help output to enumerate valid choices before invoking.","Normalize casing/whitespace of user-supplied values against the choices list.","Pin scripts to the library version whose choices set they were written against.","Prefer interactive pickers/autocomplete over free-text input for choice arguments."],"tags":["argument-validation","cli","invalid-input"],"backgroundTag":"invalid-argument-value","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}