{"record":{"id":"b7d160562a8af8c6","repo":"heygen-com/hyperframes","slug":"no-token","errorCode":"NO_TOKEN","errorMessage":"FIGMA_TOKEN is missing. One-time setup:\n  1. figma.com/settings → Security → Personal access tokens → Generate new token\n  2. Scopes (read-only is all this integration ever needs — it never writes to figma):\n       File content: Read-only   ·   File metadata: Read-only\n       Library content: Read-only  (needed for the `tokens` published-styles fallback)\n       Variables: Read-only      (optional — brand variables, requires figma Enterprise;\n                                  without it `tokens` falls back to published styles)\n  3. export FIGMA_TOKEN=\"figd_…\"  — add it to your shell profile or the project .env\n     so future sessions skip this step\nThen re-run this command.","messagePattern":"FIGMA_TOKEN is missing\\. One-time setup:\n  1\\. figma\\.com/settings → Security → Personal access tokens → Generate new token\n  2\\. Scopes \\(read-only is all this integration ever needs — it never writes to figma\\):\n       File content: Read-only   ·   File metadata: Read-only\n       Library content: Read-only  \\(needed for the `tokens` published-styles fallback\\)\n       Variables: Read-only      \\(optional — brand variables, requires figma Enterprise;\n                                  without it `tokens` falls back to published styles\\)\n  3\\. export FIGMA_TOKEN=\"figd_…\"  — add it to your shell profile or the project \\.env\n     so future sessions skip this step\nThen re-run this command\\.","errorType":"error_code","errorClass":"FigmaClientError","httpStatus":null,"severity":"error","filePath":"packages/core/src/figma/client.ts","lineNumber":198,"sourceCode":"function optionalString(value: unknown): string | undefined {\n  return typeof value === \"string\" ? value : undefined;\n}\n\nfunction toVariablePayload(payload: unknown): FigmaVariablePayload | null {\n  if (!isRecord(payload) || typeof payload.name !== \"string\") return null;\n  return {\n    name: payload.name,\n    key: optionalString(payload.key),\n    resolvedType: optionalString(payload.resolvedType),\n    valuesByMode: isRecord(payload.valuesByMode) ? payload.valuesByMode : undefined,\n    variableCollectionId: optionalString(payload.variableCollectionId),\n  };\n}\n\nexport function createFigmaClient(options: FigmaClientOptions): FigmaClient {\n  const token = options.token.trim();\n  if (token === \"\") {\n    throw new FigmaClientError(\n      \"NO_TOKEN\",\n      [\n        \"FIGMA_TOKEN is missing. One-time setup:\",\n        \"  1. figma.com/settings → Security → Personal access tokens → Generate new token\",\n        \"  2. Scopes (read-only is all this integration ever needs — it never writes to figma):\",\n        \"       File content: Read-only   ·   File metadata: Read-only\",\n        \"       Library content: Read-only  (needed for the `tokens` published-styles fallback)\",\n        \"       Variables: Read-only      (optional — brand variables, requires figma Enterprise;\",\n        \"                                  without it `tokens` falls back to published styles)\",\n        '  3. export FIGMA_TOKEN=\"figd_…\"  — add it to your shell profile or the project .env',\n        \"     so future sessions skip this step\",\n        \"Then re-run this command.\",\n      ].join(\"\\n\"),\n    );\n  }\n  const doFetch: FigmaFetch = options.fetch ?? ((url, init) => fetch(url, init));\n  const base = options.baseUrl ?? \"https://api.figma.com\";\n  const sleep = options.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/core/src/figma/client.ts#L180-L216","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Generate a read-only PAT at figma.com/settings -> Security -> Personal access tokens.","Export it in the current shell: export FIGMA_TOKEN=\"figd_xxx\", then re-run.","Persist it in the project .env (and ensure dotenv loads before createFigmaClient) or in the shell profile for future sessions.","For CI, add FIGMA_TOKEN as a masked secret in the pipeline settings."],"exampleFix":"// before — env var unset/empty, client throws at construction\nconst client = createFigmaClient({ token: process.env.FIGMA_TOKEN ?? '' });\n\n// after — load .env first, then construct\nimport 'dotenv/config';\nconst client = createFigmaClient({ token: process.env.FIGMA_TOKEN! });","handlingStrategy":"validation","validationCode":"const token = (process.env.FIGMA_TOKEN ?? '').trim();\nif (token === '') {\n  throw new Error('FIGMA_TOKEN is not set. Generate a read-only PAT at figma.com/settings.');\n}\nconst client = createFigmaClient({ token });","typeGuard":null,"tryCatchPattern":"import { FigmaClientError } from '.../figma/client';\ntry {\n  const client = createFigmaClient({ token: process.env.FIGMA_TOKEN ?? '' });\n} catch (err) {\n  if (err instanceof FigmaClientError && err.code === 'NO_TOKEN') {\n    // print setup instructions, exit gracefully\n  } else throw err;\n}","preventionTips":["Load .env at app startup (dotenv/config) before constructing the client.","Store FIGMA_TOKEN in the shell profile and in CI secrets, never in git.","Unit-test the NO_TOKEN path with an empty token to confirm your UI surfaces the setup steps."],"tags":["figma","config","auth","environment","setup"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}