heygen-com/hyperframes · error · Error

unsupported format "${raw}" — use one of ${FORMATS.join(", "

Error message

unsupported format "${raw}" — use one of ${FORMATS.join(", ")}

What it means

Thrown by parseFormat() when --format does not exactly match one of the FORMATS tuple entries (png, svg, jpg, pdf). The comparison is case- and spelling-sensitive, so 'SVG', 'JPG', 'webp', or a typo all fail. The valid set is interpolated into the message.

Source

Thrown at packages/cli/src/commands/figma/asset.ts:263

  return cleaned.length > 0 ? cleaned : undefined;
}

/** Keep the agent-readable inventory in step with the manifest (media-use
 * regenerates the same file after its writes). Best-effort: the import is
 * already durable, so an index write failure must not fail the command. */
function safeRegenerateIndex(projectDir: string): void {
  try {
    regenerateIndex(projectDir);
  } catch (err) {
    console.warn(`index.md regeneration failed: ${err instanceof Error ? err.message : err}`);
  }
}

const FORMATS: readonly FigmaAssetFormat[] = ["png", "svg", "jpg", "pdf"];

function parseFormat(raw: string): FigmaAssetFormat {
  for (const f of FORMATS) if (f === raw) return f;
  throw new Error(`unsupported format "${raw}" — use one of ${FORMATS.join(", ")}`);
}

export default defineCommand({
  meta: { name: "asset", description: "Import one or more figma nodes as frozen local assets" },
  args: {
    ref: {
      type: "positional",
      description:
        "figma URL, fileKey:nodeId, or fileKey (pass several, or comma-separate ids, to batch)",
      required: true,
    },
    format: { type: "string", description: "png | svg | jpg | pdf", default: "svg" },
    scale: { type: "string", description: "export scale (e.g. 2)" },
    description: {
      type: "string",
      description: "what this asset is (index.md + <img alt>); e.g. the layer's purpose",
    },
    entity: {

View on GitHub (pinned to c2996c8626)

Solutions

1. Use one of png, svg, jpg, pdf in lowercase
2. Omit --format to use the default (svg)
3. For raster needs not covered, pick png or jpg and post-convert with sharp/imagemagick

Example fix

// before
hyperframes figma asset AAA:1:2 --format SVG
// after
hyperframes figma asset AAA:1:2 --format svg

const FORMATS = ['png', 'svg', 'jpg', 'pdf'] as const;
type FigmaAssetFormat = typeof FORMATS[number];
function parseFormat(raw: string): FigmaAssetFormat {
  if (!FORMATS.includes(raw as FigmaAssetFormat)) {
    throw new Error(`unsupported format ${raw}; use one of ${FORMATS.join(', ')}`);
  }
  return raw as FigmaAssetFormat;
}

const FORMATS = ['png', 'svg', 'jpg', 'pdf'] as const;
function isFigmaAssetFormat(raw: unknown): raw is typeof FORMATS[number] {
  return typeof raw === 'string' && (FORMATS as readonly string[]).includes(raw);
}

When it happens

Trigger: `--format SVG` (uppercase fails — comparison is exact), `--format webp`, `--format gif`, `--format jpeg` (the tuple uses 'jpg'), a typo like `--format pngg`.

Common situations: Expecting modern formats (webp/avif) that figma's /v1/images does not support; case mismatch from copying an uppercase extension; using 'jpeg' instead of 'jpg'.

Related errors

• ref "${refInput}" has no node id — share a link with ?node-i
• all refs in one import must share a fileKey (batch is per-fi
• figma render returned non-SVG bytes for an svg export — retr
• figma asset import produced no result for "${refInput}"
• RENDER_FAILED

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