heygen-com/hyperframes · error · Error

parseFigmaRef: empty input

Error message

parseFigmaRef: empty input

What it means

Thrown by parseFigmaRef when input.trim() is the empty string — the ref contained no usable characters. parseFigmaRef is the entry point that turns a pasted figma URL or a bare 'fileKey:nodeId' token into a FigmaRef, and an empty input yields neither fileKey nor nodeId, so it fails immediately rather than producing an empty-keyed ref that would cause a confusing downstream 404.

Source

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

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) };

View on GitHub (pinned to c2996c8626)

Solutions

1. Supply a non-empty figma URL or 'fileKey:nodeId' string.
2. If reading from argv/env, default-check before calling: if (!input) throw a clearer caller-side error.
3. Trim user input in the UI layer and reject empty submissions before they reach parseFigmaRef.

Example fix

// before — argv missing, coerced to empty
const ref = parseFigmaRef(process.argv[2] ?? '');

// after — guard at the caller with a helpful message
const raw = process.argv[2];
if (!raw?.trim()) throw new Error('usage: import <figma-url-or-ref>');
const ref = parseFigmaRef(raw);

export function parseFigmaRefSafe(input: unknown) {
  if (typeof input !== 'string' || input.trim().length === 0) {
    throw new Error('a figma URL or fileKey is required');
  }
  return parseFigmaRef(input);
}

export function isNonEmptyRefInput(input: unknown): input is string {
  return typeof input === 'string' && input.trim().length > 0;
}

When it happens

Trigger: Calling parseFigmaRef(''); calling parseFigmaRef(' ') (whitespace only); a CLI arg that was not supplied and defaulted to empty; reading a ref from a config field that was left blank.

Common situations: User pressed enter without pasting a URL; a script reads process.argv[2] which is undefined and gets coerced to ''; an empty .env variable feeding the ref; a UI input field that was never filled.

Related errors

• parseFigmaRef: invalid ref "${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/4311874061ddc3bb. Report an issue: GitHub.