heygen-com/hyperframes · error · FigmaClientError

RENDER_FAILED

RENDER_FAILED

Error message

figma could not render node ${nodeId} as ${opts.format}

What it means

Thrown by renderNode (code RENDER_FAILED) when the single-node render returns either no result or a result whose url is null. renderNode is a thin wrapper over renderNodes (the batch endpoint /v1/images) — batch calls intentionally return url:null for individual nodes that figma could not render so one bad node doesn't fail the whole batch, but the single-node renderNode has no such tolerance and escalates a null url to an exception. Common when the node id is valid enough to be accepted by the API but figma cannot rasterise it (e.g. an empty frame, a component set, a locked node).

Source

Thrown at packages/core/src/figma/client.ts:315

    // per-minute, so a couple of imports in quick succession hit it and a
    // short wait clears it. Honor Retry-After when present, else exponential.
    let res: Response;
    for (let attempt = 0; ; attempt += 1) {
      res = await doFetch(`${base}${path}`, { headers: { "X-Figma-Token": token } });
      if (res.status !== 429 || attempt >= maxRetries) break;
      const wait = retryAfterMs(res) ?? 1000 * 2 ** attempt;
      await sleep(wait);
    }
    await throwForStatus(res, path, opts);
    return res.json();
  }

  return {
    async renderNode(ref, opts) {
      const nodeId = requireNodeId(ref);
      const [result] = await this.renderNodes(ref.fileKey, [nodeId], opts);
      if (!result || result.url === null)
        throw new FigmaClientError(
          "RENDER_FAILED",
          `figma could not render node ${nodeId} as ${opts.format}`,
          undefined,
          "images",
        );
      return { url: result.url, ext: opts.format };
    },

    async renderNodes(fileKey, nodeIds, opts) {
      if (nodeIds.length === 0) return [];
      // /v1/images accepts comma-separated ids — one call for the whole batch,
      // which is figma's own answer to the per-minute rate limit.
      const params = new URLSearchParams({ ids: nodeIds.join(","), format: opts.format });
      if (opts.scale !== undefined) params.set("scale", String(opts.scale));
      const body = await get(`/v1/images/${fileKey}?${params}`, {
        scopeHint: SCOPE_HINTS.fileContent,
        endpoint: "images",
      });

View on GitHub (pinned to c2996c8626)

Solutions

1. Open the node in figma and confirm it has visible, renderable content (not an empty frame or a component-set container).
2. Render a child node with actual fills/children instead of the parent container.
3. Try a different format (svg vs png) — some node types render in one but not the other.
4. If you need to tolerate per-node failures, call renderNodes directly and skip entries with url === null.

Example fix

// before — single-node call throws if figma returns url:null
const { url } = await client.renderNode(ref, { format: 'png' });

// after — batch call lets you skip unrenderable nodes
const [r] = await client.renderNodes(ref.fileKey, [ref.nodeId!], { format: 'png' });
if (!r || r.url === null) continue; // tolerate per-node failure

import { FigmaClientError } from '.../figma/client';
export function isRenderFailed(err: unknown): err is FigmaClientError {
  return err instanceof FigmaClientError && err.code === 'RENDER_FAILED';
}

// Fall back from renderNode to a tolerant batch call, skipping unrenderable nodes
try {
  return await client.renderNode(ref, opts);
} catch (err) {
  if (isRenderFailed(err)) {
    const [r] = await client.renderNodes(ref.fileKey, [ref.nodeId!], opts);
    if (r && r.url !== null) return { url: r.url, ext: opts.format };
    // give up gracefully on this node
    return null;
  }
  throw err;
}

When it happens

Trigger: Calling renderNode with a nodeId pointing at an empty/zero-size frame; rendering a node type figma refuses to rasterise (e.g. a Component Set or a Boolean Operation container); the node was deleted between parsing and rendering; an internal figma render error surfaced as a null url rather than an HTTP status.

Common situations: Copying a node id from the figma URL for a container/group that has no visual content; rendering a slice or guide node; the figma file's render backend timing out for one specific heavy frame.

Related errors

• figma ref ${ref.fileKey} has no nodeId
• NODE_NOT_FOUND
• [getRenderProgress] executionArn is required
• [renderToLambda] bucketName is required
• [renderToLambda] stateMachineArn is required

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