{"record":{"id":"d11f7f15be79a0b7","repo":"heygen-com/hyperframes","slug":"parsefigmaref-no-filekey-in-input","errorCode":null,"errorMessage":"parseFigmaRef: no fileKey in \"${input}\"","messagePattern":"parseFigmaRef: no fileKey in \"(.+?)\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/figma/parseFigmaRef.ts","lineNumber":24,"sourceCode":"  return raw.replaceAll(\"-\", \":\");\n}\n\nexport function parseFigmaRef(input: string): FigmaRef {\n  const trimmed = input.trim();\n  if (trimmed.length === 0) throw new Error(\"parseFigmaRef: empty input\");\n\n  if (!trimmed.includes(\"/\")) {\n    const colon = trimmed.indexOf(\":\");\n    if (colon === -1) return { fileKey: trimmed };\n    const fileKey = trimmed.slice(0, colon);\n    const node = trimmed.slice(colon + 1);\n    if (fileKey.length === 0) throw new Error(`parseFigmaRef: invalid ref \"${input}\"`);\n    return node.length > 0 ? { fileKey, nodeId: normalizeNodeId(node) } : { fileKey };\n  }\n\n  const keyMatch = trimmed.match(FILE_KEY_RE);\n  const fileKey = keyMatch?.[1];\n  if (fileKey === undefined) throw new Error(`parseFigmaRef: no fileKey in \"${input}\"`);\n\n  const q = trimmed.indexOf(\"?\");\n  if (q !== -1) {\n    const raw = new URLSearchParams(trimmed.slice(q + 1)).get(\"node-id\");\n    if (raw !== null && raw.length > 0) return { fileKey, nodeId: normalizeNodeId(raw) };\n  }\n  return { fileKey };\n}\n","sourceCodeStart":6,"sourceCodeEnd":33,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/core/src/figma/parseFigmaRef.ts#L6-L33","documentation":"Thrown by parseFigmaRef when the input contains a '/' (so it's treated as URL/path form) but the FILE_KEY_RE regex — \\/(?:design|file|proto)\\/([A-Za-z0-9]+) — does not match, meaning no recognisable /design/, /file/, or /proto/ segment with a key is present. The parser cannot extract a fileKey from such a string and refuses to fabricate one. A successful match would yield the fileKey capture group; absence means the URL is not a figma URL or is malformed.","triggerScenarios":"Input like 'https://example.com/foo' (host/path not figma-shaped); 'https://www.figma.com/file/' with nothing after the slash; a figma URL using a path segment the regex doesn't cover (e.g. a future /board/ or /slides/ path); a relative path like 'docs/guide' that happens to contain a slash.","commonSituations":"User pastes a non-figma URL by mistake; figma changes its URL scheme to add a new path segment not in the regex (design|file|proto); a figma URL copied without the fileKey portion; trailing slash or fragment edge cases after the path segment.","solutions":["Re-copy the URL from the figma browser address bar and confirm it contains /design/<key>/ or /file/<key>/.","If figma introduced a new path segment, update FILE_KEY_RE to include it.","For non-URL inputs, use the bare 'fileKey' or 'fileKey:nodeId' colon form instead.","Verify the pasted string wasn't truncated (missing the /design/ portion)."],"exampleFix":"// before — wrong path segment, regex misses\nparseFigmaRef('https://www.figma.com/slides/abc123/My-Deck'); // throws\n\n// after — use a supported path segment, or the bare key form\nparseFigmaRef('abc123');                          // fileKey only\nparseFigmaRef('https://www.figma.com/design/abc123/My-File?node-id=12:34');","handlingStrategy":"validation","validationCode":"const FIGMA_URL_RE = /^https?:\\/\\/(?:www\\.)?figma\\.com\\/(?:design|file|proto)\\/[A-Za-z0-9]+/i;\nexport function looksLikeFigmaUrl(input: string): boolean {\n  return FIGMA_URL_RE.test(input.trim());\n}\nif (input.includes('/') && !looksLikeFigmaUrl(input)) {\n  throw new Error(`${input} is not a recognised figma URL — expected /design|file|proto/<key>/`);\n}\nparseFigmaRef(input);","typeGuard":null,"tryCatchPattern":"try {\n  const ref = parseFigmaRef(input);\n} catch (err) {\n  if (err instanceof Error && /no fileKey/.test(err.message)) {\n    // prompt the user to paste a full figma URL\n  } else throw err;\n}","preventionTips":["Always copy URLs from the figma address bar so they include /design/<key>/.","If figma ships a new URL path segment, extend FILE_KEY_RE to cover it.","For non-URL inputs, prefer the bare 'fileKey' or 'fileKey:nodeId' colon form."],"tags":["figma","parsing","validation","url"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}