heygen-com/hyperframes · error · Error

${errorPrefix} must be ${allowed.join("|")}; got ${s}

Error message

${errorPrefix} must be ${allowed.join("|")}; got ${s}

What it means

Thrown by parseEnum when a string-union flag was supplied with a value not in the allowed set. parseEnum is the closed-set validator behind --format, --codec, --quality, and --chrome-source; the error interpolates the errorPrefix (which flag), the full allowed list, and the offending value, so the correct choices are visible in the message.

Source

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

  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);
  if ((allowed as readonly string[]).includes(s)) return s as T;
  throw new Error(`${errorPrefix} must be ${allowed.join("|")}; got ${s}`);
}

const FORMATS = [
  "mp4",
  "mov",
  "png-sequence",
  "webm",
] as const satisfies readonly DistributedFormat[];
const CODECS = ["h264", "h265"] as const;
const QUALITIES = ["draft", "standard", "high"] as const;
const CHROME_SOURCES = ["sparticuz", "chrome-headless-shell"] as const;

const parseFormat = (raw: unknown): (typeof FORMATS)[number] =>
  parseEnum(raw, FORMATS, "[lambda render] --format", "mp4")!;
const parseCodec = (raw: unknown): (typeof CODECS)[number] | undefined =>
  parseEnum(raw, CODECS, "[lambda render] --codec", undefined);
const parseQuality = (raw: unknown): (typeof QUALITIES)[number] | undefined =>
  parseEnum(raw, QUALITIES, "[lambda render] --quality", undefined);

View on GitHub (pinned to c2996c8626)

Solutions

1. Use one of the values listed in the error message exactly (case-sensitive).
2. Omit the flag to accept its default (e.g. mp4 for format, sparticuz for chrome-source).
3. Check the CLI help (`hyperframes lambda render -h`) for the current accepted values for your HyperFrames version.

Example fix

# before
hyperframes lambda render ./proj --width 1920 --height 1080 --format avi
# after
hyperframes lambda render ./proj --width 1920 --height 1080 --format mp4

// Validate enum flags against the allowed sets before invoking lambda
const FORMATS = ["mp4", "mov", "png-sequence", "webm"] as const;
const CODECS = ["h264", "h265"] as const;
function assertEnum<T extends string>(v: string, allowed: readonly T[], name: string): T {
  if (!allowed.includes(v as T)) throw new Error(`${name} must be one of ${allowed.join("|")}`);
  return v as T;
}

function isOneOf<T extends string>(v: string, allowed: readonly T[]): v is T {
  return (allowed as readonly string[]).includes(v);
}

try {
  // run lambda render
} catch (err) {
  if (/must be .+; got/.test((err as Error).message))) {
    // message lists valid values; pick one and re-run
  }
}

When it happens

Trigger: Passing `--format avi` (not in mp4|mov|png-sequence|webm); `--codec av1`; `--quality ultra`; `--chrome-source puppeteer`; or any typo of an accepted value for these four flags on `hyperframes lambda render` / `lambda render-batch` / `lambda deploy`.

Common situations: Typos (`mp5` instead of `mp4`); casing (`H264` vs `h264` — values are case-sensitive); assuming an unsupported option exists; version drift where a value was removed.

Related errors

• [lambda] ${flagName} must be a positive integer; got ${n}
• [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/63be0e97bddfe986. Report an issue: GitHub.