heygen-com/hyperframes · error · FigmaClientError

NO_TOKEN

NO_TOKEN

Error message

FIGMA_TOKEN is missing. One-time setup:
  1. figma.com/settings → Security → Personal access tokens → Generate new token
  2. Scopes (read-only is all this integration ever needs — it never writes to figma):
       File content: Read-only   ·   File metadata: Read-only
       Library content: Read-only  (needed for the `tokens` published-styles fallback)
       Variables: Read-only      (optional — brand variables, requires figma Enterprise;
                                  without it `tokens` falls back to published styles)
  3. export FIGMA_TOKEN="figd_…"  — add it to your shell profile or the project .env
     so future sessions skip this step
Then re-run this command.

What it means

Thrown by createFigmaClient (code NO_TOKEN) when the supplied token trims to empty string. Every figma REST call sends X-Figma-Token; without it the API returns 401/403 on the first request, so the client fails fast at construction with one-time setup instructions naming the exact read-only scopes the integration needs (File content, File metadata, Library content; Variables optional/Enterprise). This is a configuration error, not a network error.

Source

Thrown at packages/core/src/figma/client.ts:198

function optionalString(value: unknown): string | undefined {
  return typeof value === "string" ? value : undefined;
}

function toVariablePayload(payload: unknown): FigmaVariablePayload | null {
  if (!isRecord(payload) || typeof payload.name !== "string") return null;
  return {
    name: payload.name,
    key: optionalString(payload.key),
    resolvedType: optionalString(payload.resolvedType),
    valuesByMode: isRecord(payload.valuesByMode) ? payload.valuesByMode : undefined,
    variableCollectionId: optionalString(payload.variableCollectionId),
  };
}

export function createFigmaClient(options: FigmaClientOptions): FigmaClient {
  const token = options.token.trim();
  if (token === "") {
    throw new FigmaClientError(
      "NO_TOKEN",
      [
        "FIGMA_TOKEN is missing. One-time setup:",
        "  1. figma.com/settings → Security → Personal access tokens → Generate new token",
        "  2. Scopes (read-only is all this integration ever needs — it never writes to figma):",
        "       File content: Read-only   ·   File metadata: Read-only",
        "       Library content: Read-only  (needed for the `tokens` published-styles fallback)",
        "       Variables: Read-only      (optional — brand variables, requires figma Enterprise;",
        "                                  without it `tokens` falls back to published styles)",
        '  3. export FIGMA_TOKEN="figd_…"  — add it to your shell profile or the project .env',
        "     so future sessions skip this step",
        "Then re-run this command.",
      ].join("\n"),
    );
  }
  const doFetch: FigmaFetch = options.fetch ?? ((url, init) => fetch(url, init));
  const base = options.baseUrl ?? "https://api.figma.com";
  const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));

View on GitHub (pinned to c2996c8626)

Solutions

1. Generate a read-only PAT at figma.com/settings -> Security -> Personal access tokens.
2. Export it in the current shell: export FIGMA_TOKEN="figd_xxx", then re-run.
3. Persist it in the project .env (and ensure dotenv loads before createFigmaClient) or in the shell profile for future sessions.
4. For CI, add FIGMA_TOKEN as a masked secret in the pipeline settings.

Example fix

// before — env var unset/empty, client throws at construction
const client = createFigmaClient({ token: process.env.FIGMA_TOKEN ?? '' });

// after — load .env first, then construct
import 'dotenv/config';
const client = createFigmaClient({ token: process.env.FIGMA_TOKEN! });

const token = (process.env.FIGMA_TOKEN ?? '').trim();
if (token === '') {
  throw new Error('FIGMA_TOKEN is not set. Generate a read-only PAT at figma.com/settings.');
}
const client = createFigmaClient({ token });

import { FigmaClientError } from '.../figma/client';
try {
  const client = createFigmaClient({ token: process.env.FIGMA_TOKEN ?? '' });
} catch (err) {
  if (err instanceof FigmaClientError && err.code === 'NO_TOKEN') {
    // print setup instructions, exit gracefully
  } else throw err;
}

When it happens

Trigger: Calling createFigmaClient({ token: process.env.FIGMA_TOKEN }) when FIGMA_TOKEN is unset; token is an empty string or whitespace; the .env file is not loaded (forgot 'import "dotenv/config"' or wrong cwd); the shell profile export was never run in the current session.

Common situations: Fresh checkout without running the figma setup step; CI job missing the FIGMA_TOKEN secret; dotenv not configured so process.env.FIGMA_TOKEN is undefined and String(undefined).trim() coerces; token accidentally deleted from the shell profile.

Related errors

• BAD_TOKEN
• [BrowserManager] Chrome binary not found at PRODUCER_HEADLES
• [BrowserManager] Chrome binary not found at HYPERFRAMES_BROW
• Neither GOOGLE_API_KEY nor GEMINI_API_KEY is set.
• [renderToLambda] bucketName is required

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