Egonex-AI/Understand-Anything · error · Error

FIGMA_TOKEN is not set. Create a personal access token at ht

Error message

FIGMA_TOKEN is not set. Create a personal access token at https://www.figma.com/settings, then run: export FIGMA_TOKEN=<token>

What it means

Thrown by the FigmaApiSource constructor when the resolved token is falsy. The token defaults to process.env.FIGMA_TOKEN and can be overridden via the constructor's second argument; if neither is a non-empty string the API client cannot authenticate and refuses to construct. The message intentionally points the user at the Figma settings page and the export command.

Source

Thrown at understand-anything-plugin/packages/core/src/figma/source/api-source.ts:17

import type { FigmaSource, FigmaDocument, FigmaStyles } from "./types.js";

const FIGMA_API = "https://api.figma.com/v1";

export function parseFileKey(urlOrKey: string): string {
  const m = urlOrKey.match(/figma\.com\/(?:file|design)\/([A-Za-z0-9]+)/);
  if (m) return m[1];
  if (/^[A-Za-z0-9]+$/.test(urlOrKey.trim())) return urlOrKey.trim();
  throw new Error(`Could not parse a Figma file key from: ${urlOrKey}`);
}

export class FigmaApiSource implements FigmaSource {
  private readonly token: string;

  constructor(private readonly fileKey: string, token: string | undefined = process.env.FIGMA_TOKEN) {
    if (!token) {
      throw new Error(
        "FIGMA_TOKEN is not set. Create a personal access token at " +
        "https://www.figma.com/settings, then run: export FIGMA_TOKEN=<token>",
      );
    }
    this.token = token;
  }

  private async get<T>(path: string): Promise<T> {
    // Token travels only in the header — never in the URL, never logged.
    const res = await fetch(`${FIGMA_API}${path}`, { headers: { "X-Figma-Token": this.token } });
    if (!res.ok) {
      throw new Error(`Figma API ${path} failed: ${res.status} ${res.statusText}`);
    }
    return (await res.json()) as T;
  }

  fetchDocument(): Promise<FigmaDocument> {
    return this.get<FigmaDocument>(`/files/${this.fileKey}`);

View on GitHub (pinned to 32944829e7)

Solutions

1. Create a personal access token at https://www.figma.com/settings and run export FIGMA_TOKEN=<token> in the same shell before launching.
2. Pass the token explicitly: new FigmaApiSource(fileKey, myToken).
3. Ensure the token is exported in the environment of any CI runner, container, or spawned child process (inherit env or inject the secret).
4. Add a startup assertion that process.env.FIGMA_TOKEN is a non-empty string so the failure surfaces before work begins.

Example fix

// before
const src = new FigmaApiSource(fileKey);
// after
const src = new FigmaApiSource(fileKey, process.env.FIGMA_TOKEN);
// and ensure the env is populated: export FIGMA_TOKEN=figd_...

const token = process.env.FIGMA_TOKEN;
if (!token || token.trim().length === 0) {
  throw new Error('Set FIGMA_TOKEN before constructing FigmaApiSource');
}
const src = new FigmaApiSource(fileKey, token);

function hasFigmaToken(env: NodeJS.ProcessEnv): env is { FIGMA_TOKEN: string } {
  return typeof env.FIGMA_TOKEN === 'string' && env.FIGMA_TOKEN.length > 0;
}

try { const src = new FigmaApiSource(fileKey, token); } catch (e) { if (/FIGMA_TOKEN/.test(String((e as Error).message))) { /* surface env setup guidance */ } throw e; }

When it happens

Trigger: Constructing new FigmaApiSource(fileKey) (or with token omitted) when FIGMA_TOKEN is unset, empty, or whitespace — note the guard checks truthiness, not non-empty-after-trim, so a whitespace-only value still passes. Also fires when an explicit token argument is undefined/null/empty string.

Common situations: Running in a fresh shell without exporting FIGMA_TOKEN; the token set in one shell but not in a CI runner or a child process spawned with a sanitised env; a .env file that is not loaded; deploying to an environment where the secret was forgotten.

Related errors

• Could not parse a Figma file key from: ${urlOrKey}
• Figma API ${path} failed: ${res.status} ${res.statusText}
• A benchmark report target is a directory
• Benchmark report files must share a directory
• HTTP ${res.status}

AI-assisted analysis of Egonex-AI/Understand-Anything@32944829e7 (2026-08-12). Data as JSON: /api/errors/889f91250726b4a0. Report an issue: GitHub.