heygen-com/hyperframes · error · FigmaClientError

NODE_NOT_FOUND

NODE_NOT_FOUND

Error message

node ${nodeId} not found in ${ref.fileKey}

What it means

Thrown by nodeTree (code NODE_NOT_FOUND) when GET /v1/files/:key/nodes?ids=:nodeId returns a response whose nodes[nodeId].document is missing or lacks the id/name/type string fields. Unlike renderNode, this is a structured-data fetch, and a missing/empty document entry means figma has no such node under that fileKey — typically a wrong or stale node id, or the node was deleted. The guard checks shape, not just presence, because figma sometimes returns a malformed entry rather than an explicit error.

Source

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

    },

    async nodeTree(ref) {
      const nodeId = requireNodeId(ref);
      const params = new URLSearchParams({ ids: nodeId, geometry: "paths" });
      const body = await get(`/v1/files/${ref.fileKey}/nodes?${params}`, {
        scopeHint: SCOPE_HINTS.fileContent,
        endpoint: "files_nodes",
      });
      const nodes = isRecord(body) && isRecord(body.nodes) ? body.nodes : {};
      const entry = nodes[nodeId];
      const doc = isRecord(entry) ? entry.document : undefined;
      if (
        !isRecord(doc) ||
        typeof doc.id !== "string" ||
        typeof doc.name !== "string" ||
        typeof doc.type !== "string"
      )
        throw new FigmaClientError(
          "NODE_NOT_FOUND",
          `node ${nodeId} not found in ${ref.fileKey}`,
          undefined,
          "files_nodes",
        );
      return { ...doc, id: doc.id, name: doc.name, type: doc.type };
    },

    async fileVersion(fileKey) {
      const body = await get(`/v1/files/${fileKey}?depth=1`, {
        scopeHint: SCOPE_HINTS.fileMetadata,
        endpoint: "file_meta",
      });
      const version = isRecord(body) && typeof body.version === "string" ? body.version : "";
      const lastModified =
        isRecord(body) && typeof body.lastModified === "string" ? body.lastModified : "";
      return { version, lastModified };
    },

View on GitHub (pinned to c2996c8626)

Solutions

1. In the figma UI, re-select the frame and copy a fresh link to capture the current node-id.
2. Ensure the nodeId uses colon form ('12:34'); if you have hyphen form, run it through parseFigmaRef or replaceAll('-', ':').
3. Confirm the node still exists in the file (open it in figma) and that the fileKey matches.
4. If importing many nodes, drop the missing one and continue rather than failing the batch.

Example fix

// before — hyphen-form id, figma can't match it
await client.nodeTree({ fileKey: 'abc', nodeId: '12-34' });

// after — colon-form id (figma's native format)
await client.nodeTree({ fileKey: 'abc', nodeId: '12:34' });

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

try {
  await client.nodeTree(ref);
} catch (err) {
  if (isNodeNotFound(err)) {
    // skip this ref in a batch import, or prompt the user to re-select the node
  } else throw err;
}

When it happens

Trigger: Calling nodeTree with a nodeId that doesn't exist in the file; using a hyphen-form id ('12-34') instead of colon-form without normalisation (parseFigmaRef normalises, but a hand-built ref might not); the node was deleted after the ref was captured; the fileKey is correct but the node belongs to a different file.

Common situations: Reusing a cached figma ref across file versions where the node was removed; copying only the numeric part of a node id without the colon; pointing at a node in a branching/merged file where ids shifted.

Related errors

• figma ref ${ref.fileKey} has no nodeId
• RENDER_FAILED
• OpenRouter request failed with HTTP ${res.status}
• ref "${refInput}" has no node id — share a link with ?node-i
• figma render returned non-SVG bytes for an svg export — retr

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