heygen-com/hyperframes · error · Error

ref "${refInput}" has no node id

Error message

ref "${refInput}" has no node id

What it means

Thrown by runComponentImport() in the component command. It calls parseFigmaRef(refInput) and requires a nodeId, but unlike asset.ts's requireNodeRef it gives no remediation hint in the message. The parsing rules are identical: a bare fileKey or a URL without a non-empty ?node-id yields no nodeId.

Source

Thrown at packages/cli/src/commands/figma/component.ts:58

   * "Platform=Desktop", which would slug-collide across imports */
  name?: string;
}

export interface ComponentImportResult {
  name: string;
  htmlPath: string;
  unresolved: BindingSite[];
  rasterized: RasterizeRequest[];
  /** node ids figma refused to render as svg AND png — placeholders shipped without src */
  failedRasterize: string[];
}

export async function runComponentImport(
  refInput: string,
  deps: ComponentImportDeps,
): Promise<ComponentImportResult> {
  const ref = parseFigmaRef(refInput);
  if (!ref.nodeId) throw new Error(`ref "${refInput}" has no node id`);

  const tree = await deps.client.nodeTree(ref);
  const bindings = resolveBindings(tree, readBindings(deps.projectDir));
  const mapped = nodeToHtml(tree, bindings, { rootName: deps.name });

  const name = slugify(deps.name ?? tree.name);
  const componentDir = join(deps.projectDir, "compositions", "components", name);
  if (existsSync(componentDir))
    console.warn(
      `component dir compositions/components/${name} already exists — overwriting (rename the figma frame for a separate import)`,
    );
  mkdirSync(componentDir, { recursive: true });

  const { html, frozenAssets, failedRasterize } = await rasterizeFallback(
    mapped,
    ref.fileKey,
    componentDir,
    deps,

View on GitHub (pinned to c2996c8626)

Solutions

1. Copy the link from the specific frame in figma so it carries ?node-id=
2. Pass fileKey:nodeId, e.g. aBcDeF:1:2
3. Confirm the node id exists in the current file version

Example fix

// before
hyperframes figma component aBcDeF
// after
hyperframes figma component aBcDeF:1:2

import { parseFigmaRef } from '@hyperframes/core/figma';
const ref = parseFigmaRef(refInput);
if (!ref.nodeId) {
  throw new Error(`component import needs a node id; use fileKey:nodeId or a ?node-id= URL`);
}

import { parseFigmaRef } from '@hyperframes/core/figma';
function refHasNodeId(refInput: string): boolean {
  try { return Boolean(parseFigmaRef(refInput).nodeId); }
  catch { return false; }
}

When it happens

Trigger: `figma component <fileKey>` (bare key); `figma component https://www.figma.com/design/ABC/Name` (no node-id query); `figma component ABC:` (empty node segment).

Common situations: Pasting the file URL from the browser address bar rather than a frame's share link; assuming component import accepts a whole file like tokens import does.

Related errors

• 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(", "
• figma render download failed: content-length ${declared} exc
• figma ref ${ref.fileKey} has no nodeId

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