heygen-com/hyperframes · error

${options.surfaceLabel} --output-resolution must be one of $

Error message

${options.surfaceLabel} --output-resolution must be one of ${VALID_CANVAS_RESOLUTIONS.join("|")} (or an alias: ${aliasHint}); got ${asString}

What it means

parseOutputResolutionFlag throws when raw is non-null/non-empty AND resolveResolutionFlagPair returned { outputResolution: undefined }. Valid canonical presets are: landscape, portrait, landscape-4k, portrait-4k, square, square-4k. Valid aliases include: 1080p, hd, 4k, uhd (plus orientation-suffixed forms like 1080p-portrait, 4k-square). Anything else (e.g. '8k', '720p', 'vga') is rejected so it fails fast rather than silently degrading to composition dimensions. surfaceLabel prefixes the message so the caller knows which command rejected it.

Source

Thrown at packages/cli/src/utils/parseOutputResolution.ts:63

 * outputResolutionAspectAgnostic: false }` when the flag is absent so the
 * caller can spread the result unconditionally.
 *
 * Throws (not exits) on an unknown value — CLI callers wrap that in their
 * own errorBox / process.exit; SDK callers surface the error to their own
 * user.
 */
export function parseOutputResolutionFlag(
  raw: unknown,
  options: OutputResolutionParseOptions,
): { outputResolution: CanvasResolution | undefined; outputResolutionAspectAgnostic: boolean } {
  if (raw == null || raw === "") {
    return { outputResolution: undefined, outputResolutionAspectAgnostic: false };
  }
  const asString = String(raw);
  const { outputResolution, outputResolutionAspectAgnostic } = resolveResolutionFlagPair(asString);
  if (outputResolution) return { outputResolution, outputResolutionAspectAgnostic };
  const aliasHint = options.aliasHint ?? "1080p, 4k, uhd, hd, …";
  throw new Error(
    `${options.surfaceLabel} --output-resolution must be one of ${VALID_CANVAS_RESOLUTIONS.join("|")} ` +
      `(or an alias: ${aliasHint}); got ${asString}`,
  );
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Use one of the canonical presets: landscape, portrait, landscape-4k, portrait-4k, square, square-4k.
2. Or use a tier alias: 1080p (or hd), 4k (or uhd), optionally suffixed with an orientation (-portrait, -square).
3. Check the surface-specific aliasHint in the error — Lambda surfaces accept extra orientation-suffixed aliases.
4. Omit the flag entirely to use the composition's authored resolution.

Example fix

# before
hyperframes cloudrun render --output-resolution=8k
# after
hyperframes cloudrun render --output-resolution=4k
# (or: 1080p, uhd, landscape-4k, portrait, square-4k, ...)

import { VALID_CANVAS_RESOLUTIONS, resolveResolutionFlagPair } from '@hyperframes/core';

function isValidResolutionFlag(v: unknown): boolean {
  if (v == null || v === '') return true; // omit is valid
  return resolveResolutionFlagPair(String(v)).outputResolution !== undefined;
}

if (!isValidResolutionFlag(rawResolution)) {
  throw new Error(`Unsupported resolution. Valid: ${VALID_CANVAS_RESOLUTIONS.join(', ')} or aliases 1080p/4k/uhd/hd.`);
}

function isKnownResolution(v: unknown): v is string {
  if (typeof v !== 'string' || v === '') return false;
  return resolveResolutionFlagPair(v).outputResolution !== undefined;
}

try {
  const { outputResolution } = parseOutputResolutionFlag(raw, { surfaceLabel: '[render]' });
} catch (err) {
  if (err instanceof Error && /--output-resolution must be one of/.test(err.message)) {
    // fall back to the composition's authored resolution
    console.error(err.message);
  } else throw err;
}

When it happens

Trigger: Passing --output-resolution with an unsupported value: '8k', '720p', '2k', 'vga', 'landscape-8k', a typo like 'lansdscape', or a fully custom WxH string (this parser does not accept pixel dimensions). The strict-throw contract is deliberate — a typo must not fall back to the composition's own resolution.

Common situations: User assumes '8k' or '720p' are supported (they are not); passes a resolution alias from a different tool; typos; copy-paste of a value from older docs that has since been removed; SDK wrapper forwarding an unvalidated user string.

Related errors

• [getRenderProgress] executionArn is required
• [renderToLambda] bucketName is required
• [renderToLambda] stateMachineArn is required
• [renderToLambda] either siteHandle or projectDir must be sup
• invalid-vars

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