{"record":{"id":"16425d14f8d9f135","repo":"heygen-com/hyperframes","slug":"render-failed","errorCode":"RENDER_FAILED","errorMessage":"figma could not render node ${nodeId} as ${opts.format}","messagePattern":"figma could not render node (.+?) as (.+?)","errorType":"error_code","errorClass":"FigmaClientError","httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/figma/asset.ts","lineNumber":209,"sourceCode":"  const entity = normalizeMeta(opts.entity);\n\n  // Resolve cache hits first; batch-render only the misses.\n  const slots: (AssetImportResult | null)[] = refs.map((r) =>\n    reuseExisting(fileKey, r.nodeId, opts, version, deps, description, entity),\n  );\n  const missIndexes = slots.flatMap((s, i) => (s === null ? [i] : []));\n  try {\n    if (missIndexes.length > 0) {\n      const missNodeIds = missIndexes.map((i) => refs[i]!.nodeId);\n      const rendered = await deps.client.renderNodes(fileKey, missNodeIds, opts);\n      const byNode = new Map(rendered.map((r) => [r.nodeId, r] as const));\n      for (const i of missIndexes) {\n        const nodeId = refs[i]!.nodeId;\n        const r = byNode.get(nodeId);\n        // Keep the typed code: component import's rasterize fallback skips on\n        // RENDER_FAILED, so a plain Error here would abort the whole import.\n        if (!r || r.url === null)\n          throw new FigmaClientError(\n            \"RENDER_FAILED\",\n            `figma could not render node ${nodeId} as ${opts.format}`,\n            undefined,\n            \"images\",\n          );\n        slots[i] = await freezeAndRecord(\n          fileKey,\n          nodeId,\n          r.url,\n          r.ext,\n          opts,\n          version,\n          deps,\n          description,\n          entity,\n        );\n      }\n    }","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/commands/figma/asset.ts#L191-L227","documentation":"Thrown in the batch render loop of runAssetImportMany() when figma's /v1/images response omits a node or returns a null/empty url for it. Unlike a plain Error, this is a FigmaClientError with code 'RENDER_FAILED' — the typed code is what lets component import's rasterizeFallback catch it, retry as png, and ultimately skip the node gracefully instead of aborting the whole import.","triggerScenarios":"figma cannot render the node in the requested format (nested instances commonly fail as svg); the node was deleted or changed between the fileVersion check and the render; an unsupported format for that node type; the node id is stale.","commonSituations":"Complex/nested component instances exported as svg; a node id copied from an old version of the file; selecting a node type figma refuses to rasterize in the chosen format.","solutions":["Retry the node as png (component import does this automatically via renderWithPngRetry)","For asset import, re-run with --format png","If still failing, component import skips it with a placeholder; accept the gap or simplify the node in figma"],"exampleFix":"// before: svg render refused for a nested instance\nhyperframes figma asset AAA:1:2 --format svg\n// after: fall back to png\nhyperframes figma asset AAA:1:2 --format png","handlingStrategy":"fallback","validationCode":null,"typeGuard":"import { FigmaClientError } from '@hyperframes/core/figma';\nfunction isRenderFailed(err: unknown): err is FigmaClientError {\n  return err instanceof FigmaClientError && err.code === 'RENDER_FAILED';\n}","tryCatchPattern":"async function importWithPngFallback(ref: string, opts: AssetImportOptions, deps: AssetImportDeps) {\n  for (const format of ['svg', 'png'] as const) {\n    try {\n      return await runAssetImport(ref, { ...opts, format }, deps);\n    } catch (err) {\n      if (!(err instanceof FigmaClientError) || err.code !== 'RENDER_FAILED') throw err;\n    }\n  }\n  return null; // both formats refused — caller decides whether to skip\n}","preventionTips":["Catch FigmaClientError with code 'RENDER_FAILED' specifically so other errors still surface","Try svg then png for nodes that may be unrenderable as vectors","Skip gracefully (like component import) rather than aborting a batch"],"tags":["figma","asset","render-failed","fallback","figma-client-error"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}