{"record":{"id":"6298afc6575740b0","repo":"heygen-com/hyperframes","slug":"node-not-found","errorCode":"NODE_NOT_FOUND","errorMessage":"node ${nodeId} not found in ${ref.fileKey}","messagePattern":"node (.+?) not found in (.+?)","errorType":"error_code","errorClass":"FigmaClientError","httpStatus":null,"severity":"error","filePath":"packages/core/src/figma/client.ts","lineNumber":407,"sourceCode":"    },\n\n    async nodeTree(ref) {\n      const nodeId = requireNodeId(ref);\n      const params = new URLSearchParams({ ids: nodeId, geometry: \"paths\" });\n      const body = await get(`/v1/files/${ref.fileKey}/nodes?${params}`, {\n        scopeHint: SCOPE_HINTS.fileContent,\n        endpoint: \"files_nodes\",\n      });\n      const nodes = isRecord(body) && isRecord(body.nodes) ? body.nodes : {};\n      const entry = nodes[nodeId];\n      const doc = isRecord(entry) ? entry.document : undefined;\n      if (\n        !isRecord(doc) ||\n        typeof doc.id !== \"string\" ||\n        typeof doc.name !== \"string\" ||\n        typeof doc.type !== \"string\"\n      )\n        throw new FigmaClientError(\n          \"NODE_NOT_FOUND\",\n          `node ${nodeId} not found in ${ref.fileKey}`,\n          undefined,\n          \"files_nodes\",\n        );\n      return { ...doc, id: doc.id, name: doc.name, type: doc.type };\n    },\n\n    async fileVersion(fileKey) {\n      const body = await get(`/v1/files/${fileKey}?depth=1`, {\n        scopeHint: SCOPE_HINTS.fileMetadata,\n        endpoint: \"file_meta\",\n      });\n      const version = isRecord(body) && typeof body.version === \"string\" ? body.version : \"\";\n      const lastModified =\n        isRecord(body) && typeof body.lastModified === \"string\" ? body.lastModified : \"\";\n      return { version, lastModified };\n    },","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/core/src/figma/client.ts#L389-L425","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["In the figma UI, re-select the frame and copy a fresh link to capture the current node-id.","Ensure the nodeId uses colon form ('12:34'); if you have hyphen form, run it through parseFigmaRef or replaceAll('-', ':').","Confirm the node still exists in the file (open it in figma) and that the fileKey matches.","If importing many nodes, drop the missing one and continue rather than failing the batch."],"exampleFix":"// before — hyphen-form id, figma can't match it\nawait client.nodeTree({ fileKey: 'abc', nodeId: '12-34' });\n\n// after — colon-form id (figma's native format)\nawait client.nodeTree({ fileKey: 'abc', nodeId: '12:34' });","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { FigmaClientError } from '.../figma/client';\nexport function isNodeNotFound(err: unknown): err is FigmaClientError {\n  return err instanceof FigmaClientError && err.code === 'NODE_NOT_FOUND';\n}","tryCatchPattern":"try {\n  await client.nodeTree(ref);\n} catch (err) {\n  if (isNodeNotFound(err)) {\n    // skip this ref in a batch import, or prompt the user to re-select the node\n  } else throw err;\n}","preventionTips":["Normalise nodeId to colon form ('12:34') before calling — parseFigmaRef does this for you.","Re-capture the figma node link whenever the file is restructured to avoid stale ids.","When importing many nodes, drop NODE_NOT_FOUND entries rather than failing the whole batch."],"tags":["figma","not-found","api","nodes"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}