{"record":{"id":"2334b7d3add3be01","repo":"jackwener/OpenCLI","slug":"argument-argdef-name-must-be-a-valid-integer","errorCode":null,"errorMessage":"Argument \"${argDef.name}\" must be a valid integer. Received: \"${val}\"","messagePattern":"Argument \"(.+?)\" must be a valid integer\\. Received: \"(.+?)\"","errorType":"validation","errorClass":"ArgumentError","httpStatus":null,"severity":"error","filePath":"src/execution.ts","lineNumber":74,"sourceCode":"\n  for (const argDef of cmdArgs) {\n    const val = result[argDef.name];\n\n    if (argDef.required && (val === undefined || val === null || val === '')) {\n      throw new ArgumentError(\n        `Argument \"${argDef.name}\" is required.`,\n        argDef.help ?? `Provide a value for --${argDef.name}`,\n      );\n    }\n\n    if (val !== undefined && val !== null) {\n      if (argDef.type === 'int' || argDef.type === 'number') {\n        const num = Number(val);\n        if (!Number.isFinite(num)) {\n          throw new ArgumentError(`Argument \"${argDef.name}\" must be a valid number. Received: \"${val}\"`);\n        }\n        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        }","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/src/execution.ts#L56-L92","documentation":"For arguments typed 'int', coerceAndValidateArgs requires the numeric value to be a whole number. After the finite-number check passes, a non-integer value (e.g. 2.5) throws ArgumentError stating the argument must be a valid integer.","triggerScenarios":"Passing --workers 2.5, --retries 1.0 with a decimal representation via kwargs (number 1.5), or any fractional value to an int-typed flag.","commonSituations":"Dividing a total by a count in scripts (total/2) producing fractions; percentages passed as 0.5 where an integer count is expected; defaults copied from float-based configs.","solutions":["Pass a whole number, e.g. --workers 3.","Round/ceil the computed value in the calling script (Math.ceil(x)) before passing.","If fractional values are legitimate, check whether the argument should be typed 'number' instead of 'int' (library-side change)."],"exampleFix":"// before\nopencli run --workers $((total / 2))   # 2.5\n// after\nopencli run --workers $(( (total + 1) / 2 ))   # integer","handlingStrategy":"validation","validationCode":"function toInt(v: unknown, label: string): number {\n  const n = Number(v);\n  if (!Number.isFinite(n) || !Number.isInteger(n)) throw new Error(`${label} must be an integer, got: ${String(v)}`);\n  return n;\n}\nkwargs.workers = toInt(kwargs.workers, '--workers');","typeGuard":"const isInt = (v: unknown): v is number =>\n  typeof v === 'number' && Number.isInteger(v);","tryCatchPattern":"try {\n  await opencli.run(cmd, kwargs);\n} catch (e) {\n  if (/must be a valid integer/.test(e.message)) {\n    console.error(`${e.message} — round the value before passing (Math.ceil/Math.floor).`);\n  } else throw e;\n}","preventionTips":["Round results of division before passing them to int-typed flags.","Never pass fractional counts like 0.5 or 2.5.","Use Math.ceil/floor explicitly in scripts that compute counts."],"tags":["cli","type-coercion","integer"],"backgroundTag":"invalid-number-argument","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}