heygen-com/hyperframes · error · Error

parseFigmaRef: no fileKey in "${input}"

Error message

parseFigmaRef: no fileKey in "${input}"

What it means

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.

Source

Thrown at packages/core/src/figma/parseFigmaRef.ts:24

  return raw.replaceAll("-", ":");
}

export function parseFigmaRef(input: string): FigmaRef {
  const trimmed = input.trim();
  if (trimmed.length === 0) throw new Error("parseFigmaRef: empty input");

  if (!trimmed.includes("/")) {
    const colon = trimmed.indexOf(":");
    if (colon === -1) return { fileKey: trimmed };
    const fileKey = trimmed.slice(0, colon);
    const node = trimmed.slice(colon + 1);
    if (fileKey.length === 0) throw new Error(`parseFigmaRef: invalid ref "${input}"`);
    return node.length > 0 ? { fileKey, nodeId: normalizeNodeId(node) } : { fileKey };
  }

  const keyMatch = trimmed.match(FILE_KEY_RE);
  const fileKey = keyMatch?.[1];
  if (fileKey === undefined) throw new Error(`parseFigmaRef: no fileKey in "${input}"`);

  const q = trimmed.indexOf("?");
  if (q !== -1) {
    const raw = new URLSearchParams(trimmed.slice(q + 1)).get("node-id");
    if (raw !== null && raw.length > 0) return { fileKey, nodeId: normalizeNodeId(raw) };
  }
  return { fileKey };
}

View on GitHub (pinned to c2996c8626)

Solutions

1. Re-copy the URL from the figma browser address bar and confirm it contains /design/<key>/ or /file/<key>/.
2. If figma introduced a new path segment, update FILE_KEY_RE to include it.
3. For non-URL inputs, use the bare 'fileKey' or 'fileKey:nodeId' colon form instead.
4. Verify the pasted string wasn't truncated (missing the /design/ portion).

Example fix

// before — wrong path segment, regex misses
parseFigmaRef('https://www.figma.com/slides/abc123/My-Deck'); // throws

// after — use a supported path segment, or the bare key form
parseFigmaRef('abc123');                          // fileKey only
parseFigmaRef('https://www.figma.com/design/abc123/My-File?node-id=12:34');

const FIGMA_URL_RE = /^https?:\/\/(?:www\.)?figma\.com\/(?:design|file|proto)\/[A-Za-z0-9]+/i;
export function looksLikeFigmaUrl(input: string): boolean {
  return FIGMA_URL_RE.test(input.trim());
}
if (input.includes('/') && !looksLikeFigmaUrl(input)) {
  throw new Error(`${input} is not a recognised figma URL — expected /design|file|proto/<key>/`);
}
parseFigmaRef(input);

try {
  const ref = parseFigmaRef(input);
} catch (err) {
  if (err instanceof Error && /no fileKey/.test(err.message)) {
    // prompt the user to paste a full figma URL
  } else throw err;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• parseFigmaRef: empty input
• parseFigmaRef: invalid ref "${input}"
• ref "${refInput}" has no node id — share a link with ?node-i
• all refs in one import must share a fileKey (batch is per-fi
• unsupported format "${raw}" — use one of ${FORMATS.join(", "

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