{"record":{"id":"49fa7b8e561e1e36","repo":"Egonex-AI/Understand-Anything","slug":"could-not-parse-a-figma-file-key-from-urlorkey","errorCode":null,"errorMessage":"Could not parse a Figma file key from: ${urlOrKey}","messagePattern":"Could not parse a Figma file key from: (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/packages/core/src/figma/source/api-source.ts","lineNumber":9,"sourceCode":"import type { FigmaSource, FigmaDocument, FigmaStyles } from \"./types.js\";\n\nconst FIGMA_API = \"https://api.figma.com/v1\";\n\nexport function parseFileKey(urlOrKey: string): string {\n  const m = urlOrKey.match(/figma\\.com\\/(?:file|design)\\/([A-Za-z0-9]+)/);\n  if (m) return m[1];\n  if (/^[A-Za-z0-9]+$/.test(urlOrKey.trim())) return urlOrKey.trim();\n  throw new Error(`Could not parse a Figma file key from: ${urlOrKey}`);\n}\n\nexport class FigmaApiSource implements FigmaSource {\n  private readonly token: string;\n\n  constructor(private readonly fileKey: string, token: string | undefined = process.env.FIGMA_TOKEN) {\n    if (!token) {\n      throw new Error(\n        \"FIGMA_TOKEN is not set. Create a personal access token at \" +\n        \"https://www.figma.com/settings, then run: export FIGMA_TOKEN=<token>\",\n      );\n    }\n    this.token = token;\n  }\n\n  private async get<T>(path: string): Promise<T> {\n    // Token travels only in the header — never in the URL, never logged.\n    const res = await fetch(`${FIGMA_API}${path}`, { headers: { \"X-Figma-Token\": this.token } });","sourceCodeStart":1,"sourceCodeEnd":27,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/32944829e7a63a9fa9c55d811d7f98a9530c6a6a/understand-anything-plugin/packages/core/src/figma/source/api-source.ts#L1-L27","documentation":"Thrown by parseFileKey when the input string matches neither a figma.com file/design URL nor a bare alphanumeric file key. The function uses two regexes — one for URLs (capturing the key after /file/ or /design/) and one for raw keys — and only throws when both fail. It is the entry point that normalises user input into the fileKey passed to FigmaApiSource.","triggerScenarios":"Calling parseFileKey with a string that contains neither 'figma.com/file/' nor 'figma.com/design/' AND is not purely [A-Za-z0-9]. Examples: a URL with a query-only form, a key containing dashes/underscores, an empty string, a node deep-link URL, or a copied share link of an unrecognised shape.","commonSituations":"Pasting a Figma share URL that points at a specific node (e.g. ?node-id=... without the /file/ prefix), using a Figma key that includes hyphens, passing a trimmed-but-malformed string, or migrating from a different Figma URL scheme after a Figma UI change.","solutions":["Pass the canonical Figma URL in the form https://www.figma.com/file/<KEY>/ or https://www.figma.com/design/<KEY>/.","Pass only the raw file key, ensuring it contains solely A-Z, a-z, 0-9 characters (no dashes, underscores, or slashes).","Strip query strings and node-id fragments from the URL before calling parseFileKey.","If your key legitimately contains other characters, pre-validate and extract the key yourself before passing it in."],"exampleFix":"// before\nparseFileKey('https://www.figma.com/design/abc-123-DEF?node-id=1:2')\n// after — pass the bare key, only alphanumerics\nparseFileKey('abc123DEF')","handlingStrategy":"validation","validationCode":"function looksLikeFileKey(s: string): boolean {\n  const u = s.match(/figma\\.com\\/(?:file|design)\\/([A-Za-z0-9]+)/);\n  if (u) return true;\n  return /^[A-Za-z0-9]+$/.test(s.trim());\n}\n// call before parseFileKey:\nif (!looksLikeFileKey(input)) throw new Error('Input is neither a figma.com URL nor a bare alphanumeric key');","typeGuard":"function isParsableFileKey(value: unknown): value is string {\n  return typeof value === 'string' &&\n    (Boolean(value.match(/figma\\.com\\/(?:file|design)\\/([A-Za-z0-9]+)/)) ||\n      /^[A-Za-z0-9]+$/.test(value.trim()));\n}","tryCatchPattern":"try { const key = parseFileKey(userInput); } catch (e) { /* prompt the user for a valid figma.com URL or raw key */ throw e; }","preventionTips":["Accept figma.com URLs directly from users and let parseFileKey extract the key rather than asking for a raw key.","Trim and strip query strings/node-id fragments before parsing.","Validate input shape with isParsableFileKey before calling parseFileKey to give a clearer error."],"tags":["figma","input-validation","regex"],"backgroundTag":null,"analyzedSha":"32944829e7a63a9fa9c55d811d7f98a9530c6a6a","analyzedAt":"2026-08-12T10:25:44.261Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}