Egonex-AI/Understand-Anything · error · Error

Could not parse a Figma file key from

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.

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.

Appendix: 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)