{"record":{"id":"b4591f9db15a641f","repo":"heygen-com/hyperframes","slug":"lambda-flagname-must-be-a-positive-integer-g","errorCode":null,"errorMessage":"[lambda] ${flagName} must be a positive integer; got ${n}","messagePattern":"\\[lambda\\] (.+?) must be a positive integer; got (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/lambda.ts","lineNumber":444,"sourceCode":"  },\n});\n\nfunction parseIntFlag(raw: unknown): number | undefined {\n  if (raw === undefined || raw === null || raw === \"\") return undefined;\n  const n = Number.parseInt(String(raw), 10);\n  return Number.isFinite(n) ? n : undefined;\n}\n\n/**\n * Parse a flag that must be a positive integer (>= 1) when supplied.\n * Negative values or non-integers fail loudly instead of flowing into\n * the SDK and producing opaque AWS validation errors mid-render.\n */\nfunction parsePositiveInt(raw: unknown, flagName: string): number | undefined {\n  const n = parseIntFlag(raw);\n  if (n === undefined) return undefined;\n  if (!Number.isInteger(n) || n < 1) {\n    throw new Error(`[lambda] ${flagName} must be a positive integer; got ${n}`);\n  }\n  return n;\n}\n\n/**\n * Parse a string-union flag against a closed set of allowed values.\n * Returns `defaultValue` (which may be `undefined`) when the input is\n * empty; throws with a flag-specific message when the value is set\n * but unrecognised.\n */\nfunction parseEnum<T extends string>(\n  raw: unknown,\n  allowed: readonly T[],\n  errorPrefix: string,\n  defaultValue: T | undefined,\n): T | undefined {\n  if (raw === undefined || raw === null || raw === \"\") return defaultValue;\n  const s = String(raw);","sourceCodeStart":426,"sourceCodeEnd":462,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/lambda.ts#L426-L462","documentation":"Thrown by parsePositiveInt when a numeric CLI flag was supplied but the parsed value is not a positive (≥1) integer. The function exists specifically to fail loudly at parse time rather than letting a bad value (zero, negative, float) reach the AWS SDK and trigger an opaque mid-render validation error. The flag name is interpolated so the message names the offending flag.","triggerScenarios":"Passing a value like `--width 0`, `--height -100`, `--concurrency 2.5`, `--chunk-size -8`, `--max-parallel-chunks 0`, `--memory abc` (Number.parseInt yields NaN, but NaN<1 is the path), or any non-integer/non-positive number to a flag routed through parsePositiveInt (--width, --height, --concurrency, --memory, --chunk-size, --max-parallel-chunks, --target-chunk-frames, --max-concurrent, --wait-interval-ms).","commonSituations":"Passing a fractional or zero value; a negative from a misconfigured env var; a typo like `--width 1920px` (parseInt drops the 'px' and succeeds, but `--width 1.5px`-style inputs that parse to a non-integer fail); shell math that underflowed to 0.","solutions":["Pass a whole number ≥1 for the flag named in the message (e.g. `--width 1920`).","Drop the flag entirely if you want the default — parsePositiveInt returns undefined for absent/empty input and the caller applies its default.","Double-check shell variable expansion: `[ \"$W\" -ge 1 ]` before passing."],"exampleFix":"# before\nhyperframes lambda render ./proj --width 0 --height 1080\n# after\nhyperframes lambda render ./proj --width 1920 --height 1080","handlingStrategy":"validation","validationCode":"// Validate numeric flags before passing them to the lambda command\nfunction positiveInt(raw: string | undefined, name: string): number {\n  if (raw === undefined || raw === \"\") throw new Error(`${name} is required`);\n  const n = Number.parseInt(raw, 10);\n  if (!Number.isInteger(n) || n < 1) throw new Error(`${name} must be a positive integer`);\n  return n;\n}","typeGuard":"function isPositiveInt(v: unknown): v is number {\n  return typeof v === \"number\" && Number.isInteger(v) && v >= 1;\n}","tryCatchPattern":"try {\n  // call the lambda command / parsePositiveInt\n} catch (err) {\n  if (/must be a positive integer/.test((err as Error).message))) {\n    // the flag name and bad value are in the message; fix and re-run\n  }\n}","preventionTips":["In shell, guard with arithmetic tests: `(( W >= 1 )) || exit 1`.","For programmatic callers, parse with isPositiveInt before constructing args.","Omit a numeric flag when you want its default rather than passing 0."],"tags":["cli","input-validation","lambda","numeric","args"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}