Egonex-AI/Understand-Anything · error · Error

Could not parse a Figma file key from: ${urlOrKey}

Error message

Could not parse a Figma file key from: ${urlOrKey}

What it means

Thrown by parseFileKey when the input string matches neither a figma.com file/design URL nor a bare alphanumeric file key. The function uses two regexes — one for URLs (capturing the key after /file/ or /design/) and one for raw keys — and only throws when both fail. It is the entry point that normalises user input into the fileKey passed to FigmaApiSource.

Source

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

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

View on GitHub (pinned to 32944829e7)

Solutions

  1. Pass the canonical Figma URL in the form https://www.figma.com/file/<KEY>/ or https://www.figma.com/design/<KEY>/.
  2. Pass only the raw file key, ensuring it contains solely A-Z, a-z, 0-9 characters (no dashes, underscores, or slashes).
  3. Strip query strings and node-id fragments from the URL before calling parseFileKey.
  4. If your key legitimately contains other characters, pre-validate and extract the key yourself before passing it in.

Example fix

// before
parseFileKey('https://www.figma.com/design/abc-123-DEF?node-id=1:2')
// after — pass the bare key, only alphanumerics
parseFileKey('abc123DEF')
Defensive patterns

Strategy: validation

Validate before calling

function looksLikeFileKey(s: string): boolean {
  const u = s.match(/figma\.com\/(?:file|design)\/([A-Za-z0-9]+)/);
  if (u) return true;
  return /^[A-Za-z0-9]+$/.test(s.trim());
}
// call before parseFileKey:
if (!looksLikeFileKey(input)) throw new Error('Input is neither a figma.com URL nor a bare alphanumeric key');

Type guard

function isParsableFileKey(value: unknown): value is string {
  return typeof value === 'string' &&
    (Boolean(value.match(/figma\.com\/(?:file|design)\/([A-Za-z0-9]+)/)) ||
      /^[A-Za-z0-9]+$/.test(value.trim()));
}

Try / catch

try { const key = parseFileKey(userInput); } catch (e) { /* prompt the user for a valid figma.com URL or raw key */ throw e; }

Prevention

When it happens

Trigger: Calling parseFileKey with a string that contains neither 'figma.com/file/' nor 'figma.com/design/' AND is not purely [A-Za-z0-9]. Examples: a URL with a query-only form, a key containing dashes/underscores, an empty string, a node deep-link URL, or a copied share link of an unrecognised shape.

Common situations: Pasting a Figma share URL that points at a specific node (e.g. ?node-id=... without the /file/ prefix), using a Figma key that includes hyphens, passing a trimmed-but-malformed string, or migrating from a different Figma URL scheme after a Figma UI change.

Related errors

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