{"record":{"id":"12cd73c48328d24b","repo":"heygen-com/hyperframes","slug":"unsupported-format-raw-use-one-of-formats","errorCode":null,"errorMessage":"unsupported format \"${raw}\" — use one of ${FORMATS.join(\", \")}","messagePattern":"unsupported format \"(.+?)\" — use one of (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/figma/asset.ts","lineNumber":263,"sourceCode":"  return cleaned.length > 0 ? cleaned : undefined;\n}\n\n/** Keep the agent-readable inventory in step with the manifest (media-use\n * regenerates the same file after its writes). Best-effort: the import is\n * already durable, so an index write failure must not fail the command. */\nfunction safeRegenerateIndex(projectDir: string): void {\n  try {\n    regenerateIndex(projectDir);\n  } catch (err) {\n    console.warn(`index.md regeneration failed: ${err instanceof Error ? err.message : err}`);\n  }\n}\n\nconst FORMATS: readonly FigmaAssetFormat[] = [\"png\", \"svg\", \"jpg\", \"pdf\"];\n\nfunction parseFormat(raw: string): FigmaAssetFormat {\n  for (const f of FORMATS) if (f === raw) return f;\n  throw new Error(`unsupported format \"${raw}\" — use one of ${FORMATS.join(\", \")}`);\n}\n\nexport default defineCommand({\n  meta: { name: \"asset\", description: \"Import one or more figma nodes as frozen local assets\" },\n  args: {\n    ref: {\n      type: \"positional\",\n      description:\n        \"figma URL, fileKey:nodeId, or fileKey (pass several, or comma-separate ids, to batch)\",\n      required: true,\n    },\n    format: { type: \"string\", description: \"png | svg | jpg | pdf\", default: \"svg\" },\n    scale: { type: \"string\", description: \"export scale (e.g. 2)\" },\n    description: {\n      type: \"string\",\n      description: \"what this asset is (index.md + <img alt>); e.g. the layer's purpose\",\n    },\n    entity: {","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/figma/asset.ts#L245-L281","documentation":"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.","triggerScenarios":"`--format SVG` (uppercase fails — comparison is exact), `--format webp`, `--format gif`, `--format jpeg` (the tuple uses 'jpg'), a typo like `--format pngg`.","commonSituations":"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'.","solutions":["Use one of png, svg, jpg, pdf in lowercase","Omit --format to use the default (svg)","For raster needs not covered, pick png or jpg and post-convert with sharp/imagemagick"],"exampleFix":"// before\nhyperframes figma asset AAA:1:2 --format SVG\n// after\nhyperframes figma asset AAA:1:2 --format svg","handlingStrategy":"validation","validationCode":"const FORMATS = ['png', 'svg', 'jpg', 'pdf'] as const;\ntype FigmaAssetFormat = typeof FORMATS[number];\nfunction parseFormat(raw: string): FigmaAssetFormat {\n  if (!FORMATS.includes(raw as FigmaAssetFormat)) {\n    throw new Error(`unsupported format ${raw}; use one of ${FORMATS.join(', ')}`);\n  }\n  return raw as FigmaAssetFormat;\n}","typeGuard":"const FORMATS = ['png', 'svg', 'jpg', 'pdf'] as const;\nfunction isFigmaAssetFormat(raw: unknown): raw is typeof FORMATS[number] {\n  return typeof raw === 'string' && (FORMATS as readonly string[]).includes(raw);\n}","tryCatchPattern":null,"preventionTips":["Always lowercase the format string before validation","Remember the tuple uses 'jpg', not 'jpeg'","Default to omitting --format (svg) unless you need raster"],"tags":["figma","asset","validation","format"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}