jackwener/OpenCLI · error · ArgumentError

Argument "${argDef.name}" must be one of: ${argDef.choices.j

Error message

Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"

What it means

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.

Source

Thrown at src/execution.ts:91

        if (argDef.type === 'int' && !Number.isInteger(num)) {
          throw new ArgumentError(`Argument "${argDef.name}" must be a valid integer. Received: "${val}"`);
        }
        result[argDef.name] = num;
      } else if (argDef.type === 'boolean' || argDef.type === 'bool') {
        if (typeof val === 'string') {
          const lower = val.toLowerCase();
          if (lower === 'true' || lower === '1') result[argDef.name] = true;
          else if (lower === 'false' || lower === '0') result[argDef.name] = false;
          else throw new ArgumentError(`Argument "${argDef.name}" must be a boolean (true/false). Received: "${val}"`);
        } else {
          result[argDef.name] = Boolean(val);
        }
      }

      const coercedVal = result[argDef.name];
      if (argDef.choices && argDef.choices.length > 0) {
        if (!argDef.choices.map(String).includes(String(coercedVal))) {
          throw new ArgumentError(`Argument "${argDef.name}" must be one of: ${argDef.choices.join(', ')}. Received: "${coercedVal}"`);
        }
      }
    } else if (argDef.default !== undefined) {
      result[argDef.name] = argDef.default;
    }
  }
  return result;
}

async function runCommand(
  cmd: CliCommand,
  page: IPage | null,
  kwargs: CommandArgs,
  debug: boolean,
): Promise<unknown> {
  const internal = cmd as InternalCliCommand;
  if (internal._lazy && internal._modulePath) {
    const modulePath = internal._modulePath;

View on GitHub (pinned to 49907e53dc)

Solutions

1. Change the argument value to one of the choices listed in the error message (they are echoed verbatim after 'must be one of:').
2. Check the exact casing/spelling of your value — the comparison is string-exact after coercion, so 'Prod' fails when choices are ['prod'].
3. 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.
4. If the value should legitimately be allowed, update the command's argDef.choices in the adapter definition and re-register the command.

Example fix

// before
mycli deploy --env staging   // ArgumentError: Argument "env" must be one of: prod, dev. Received: "staging"

// after
mycli deploy --env prod

function validateChoices(argDef, value) {
  if (argDef?.choices?.length && !argDef.choices.map(String).includes(String(value))) {
    throw new Error(`"${value}" is not one of: ${argDef.choices.join(', ')}`);
  }
}
// call before dispatch: validateChoices(cmd.args?.find(a => a.name === 'env'), kwargs.env)

function isAllowedChoice(value, choices) {
  return choices.map(String).includes(String(value));
}

When it happens

Trigger: 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'.

Common situations: 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.

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

• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty
• --to station must not be empty
• --seat-types must contain only 12306 seat letters/digits (A-
• --from and --to must differ; both resolved to ${fromStation.

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/8445e1aeedffbd51. Report an issue: GitHub.