heygen-com/hyperframes · error · Error

[lambda] ${flagName} must be a positive integer; got ${n}

Error message

[lambda] ${flagName} must be a positive integer; got ${n}

What it means

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.

Source

Thrown at packages/cli/src/commands/lambda.ts:444

  },
});

function parseIntFlag(raw: unknown): number | undefined {
  if (raw === undefined || raw === null || raw === "") return undefined;
  const n = Number.parseInt(String(raw), 10);
  return Number.isFinite(n) ? n : undefined;
}

/**
 * Parse a flag that must be a positive integer (>= 1) when supplied.
 * Negative values or non-integers fail loudly instead of flowing into
 * the SDK and producing opaque AWS validation errors mid-render.
 */
function parsePositiveInt(raw: unknown, flagName: string): number | undefined {
  const n = parseIntFlag(raw);
  if (n === undefined) return undefined;
  if (!Number.isInteger(n) || n < 1) {
    throw new Error(`[lambda] ${flagName} must be a positive integer; got ${n}`);
  }
  return n;
}

/**
 * Parse a string-union flag against a closed set of allowed values.
 * Returns `defaultValue` (which may be `undefined`) when the input is
 * empty; throws with a flag-specific message when the value is set
 * but unrecognised.
 */
function parseEnum<T extends string>(
  raw: unknown,
  allowed: readonly T[],
  errorPrefix: string,
  defaultValue: T | undefined,
): T | undefined {
  if (raw === undefined || raw === null || raw === "") return defaultValue;
  const s = String(raw);

View on GitHub (pinned to c2996c8626)

Solutions

1. Pass a whole number ≥1 for the flag named in the message (e.g. `--width 1920`).
2. Drop the flag entirely if you want the default — parsePositiveInt returns undefined for absent/empty input and the caller applies its default.
3. Double-check shell variable expansion: `[ "$W" -ge 1 ]` before passing.

Example fix

# before
hyperframes lambda render ./proj --width 0 --height 1080
# after
hyperframes lambda render ./proj --width 1920 --height 1080

// Validate numeric flags before passing them to the lambda command
function positiveInt(raw: string | undefined, name: string): number {
  if (raw === undefined || raw === "") throw new Error(`${name} is required`);
  const n = Number.parseInt(raw, 10);
  if (!Number.isInteger(n) || n < 1) throw new Error(`${name} must be a positive integer`);
  return n;
}

function isPositiveInt(v: unknown): v is number {
  return typeof v === "number" && Number.isInteger(v) && v >= 1;
}

try {
  // call the lambda command / parsePositiveInt
} catch (err) {
  if (/must be a positive integer/.test((err as Error).message))) {
    // the flag name and bad value are in the message; fix and re-run
  }
}

When it happens

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

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

Related errors

• ${errorPrefix} must be ${allowed.join("|")}; got ${s}
• [lambda policies validate] usage: hyperframes lambda policie
• Grade entry "${label}" must include a grading value
• --luts must include at least one LUT path
• --for <path> is required

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/b4591f9db15a641f. Report an issue: GitHub.