heygen-com/hyperframes · error · Error

parseFigmaRef: invalid ref "${input}"

Error message

parseFigmaRef: invalid ref "${input}"

What it means

Thrown by parseFigmaRef when the input has no '/' but does have a colon, AND the substring before the colon (the would-be fileKey) is empty. This is the ':nodeId' / ' :1234' shape — a ref that names a node but no file. Because fileKey is the one field that must always be present on a FigmaRef, the parser rejects this combination outright rather than returning { fileKey: '' }. A colon-form with a non-empty fileKey (e.g. 'abc:12:34') is accepted and the node part normalised.

Source

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

import type { FigmaRef } from "./types";

const FILE_KEY_RE = /\/(?:design|file|proto)\/([A-Za-z0-9]+)/;

function normalizeNodeId(raw: string): string {
  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. Provide the fileKey before the colon: 'aBcDeF1234:12:34'.
2. Prefer the full figma URL form (parseFigmaRef handles the URL parsing) to avoid manual colon-form mistakes.
3. If building the ref programmatically, assert fileKey is non-empty before concatenating.

Example fix

// before — fileKey side empty
const ref = parseFigmaRef(`:${nodeId}`);

// after — fileKey included
const ref = parseFigmaRef(`${fileKey}:${nodeId}`);

export function buildColonRef(fileKey: string, nodeId: string): string {
  if (!fileKey) throw new Error('fileKey is required before the colon');
  return `${fileKey}:${nodeId}`;
}
parseFigmaRef(buildColonRef(fileKey, nodeId));

try {
  const ref = parseFigmaRef(input);
} catch (err) {
  if (err instanceof Error && /invalid ref/.test(err.message)) {
    // prompt user for the fileKey portion
  } else throw err;
}

When it happens

Trigger: Input like ':12:34' (fileKey missing, node present); input like ' :node' after trimming; a ref string that lost its fileKey prefix during string manipulation; a user typing only the nodeId thinking that was the whole ref.

Common situations: User pastes only the node-id portion copied from the figma URL's query string; a script concatenates ':' + nodeId but leaves the fileKey side blank due to an upstream bug; refactoring that drops the fileKey variable.

Related errors

• parseFigmaRef: empty input
• parseFigmaRef: no fileKey in "${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/e6faebf75537c953. Report an issue: GitHub.