figma-advanced-troubleshooting

Deep debugging for Figma API issues: network analysis, response inspection, and support escalation. Use when standard troubleshooting fails, diagnosing intermittent failures, or preparing detailed evidence for Figma support. Trigger with phrases like "figma hard bug", "figma mystery error", "figma deep debug", "figma intermittent failure", "figma support ticket".

仓库: jeremylongshore/claude-code-plugins-plus-skills
最近来源活动: 2026年7月17日 22:18
检测到的 SKILL.md 语言: 英语
星标: 2,604
分支: 378

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

name	figma-advanced-troubleshooting
description	Deep debugging for Figma API issues: network analysis, response inspection, and support escalation. Use when standard troubleshooting fails, diagnosing intermittent failures, or preparing detailed evidence for Figma support. Trigger with phrases like "figma hard bug", "figma mystery error", "figma deep debug", "figma intermittent failure", "figma support ticket".
allowed-tools	Read, Grep, Bash(curl:), Bash(node:)
version	1.6.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","figma"]
compatibility	Designed for Claude Code

Figma Advanced Troubleshooting

Overview

Deep debugging techniques for complex Figma REST API issues that resist standard error handling: intermittent failures, unexpected response shapes, rate limit edge cases, and large file timeouts.

Prerequisites

Access to application logs
curl with verbose mode for network inspection
Figma API credentials for testing

Instructions

Step 1: Verbose Request Inspection

# Full HTTP request/response trace for a Figma API call
curl -v -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1" 2>&1 \
  | tee figma-debug-trace.txt

# Extract key diagnostic info:
# - TLS version and cipher
# - Response status and headers
# - Timing breakdown
curl -w "
DNS:        %{time_namelookup}s
Connect:    %{time_connect}s
TLS:        %{time_appconnect}s
TTFB:       %{time_starttransfer}s
Total:      %{time_total}s
Size:       %{size_download} bytes
Status:     %{http_code}
" -s -o /dev/null \
  -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1"

Step 2: Response Shape Validation

// Figma API responses can be unexpectedly shaped when:
// - File is empty or newly created
// - Nodes have been deleted between requests
// - Plugin data is corrupted

function validateFileResponse(data: any): string[] {
  const issues: string[] = [];

  if (!data.document) issues.push();
   (!data.?.?.) issues.();
   ( data. !== ) issues.();
   (!data.) issues.();

  
   (data.) {
     ( [id, node]  .(data.)) {
       (node === ) issues.();
    }
  }

  
   (data.) {
     ( [id, url]  .(data.)) {
       (url === ) issues.();
    }
  }

   issues;
}

// Problem: Figma rate limits are per-user, per-minute, but the exact
// limit is not published and varies by plan tier and seat type.

// Diagnostic: measure your actual limit by counting successful requests
async function measureRateLimit(token: string): Promise<{
  requestsMade: number;
  firstRateLimitAt: number | null;
  retryAfter: number | null;
}> {
  let count = 0;
  let rateLimitAt: number | null = null;
  let retryAfter: number | null = null;

  // Make requests until rate limited (use a read-only endpoint)
  while (count < 200) {
    const res = await fetch('https://api.figma.com/v1/me', {
      headers: { 'X-Figma-Token': token },
    });

    if (res.status === 429) {
      rateLimitAt = count;
      retryAfter = parseInt(res.headers.get('Retry-After') || '0');
      break;
    }

    count++;
    // Small delay to avoid instant burst
    await new Promise(r => setTimeout(r, 100));
  }

  return { requestsMade: count, firstRateLimitAt: rateLimitAt, retryAfter };
}

// Large Figma files (1000+ components) can cause:
// - Response timeouts (>30s)
// - Memory issues (100+ MB JSON)
// - Rate limits from repeated retries

// Strategy: chunk the file by page
async function fetchLargeFileSafely(fileKey: string, token: string) {
  // 1. Get file metadata with depth=1 (just pages, not children)
  const meta = await fetch(
    `https://api.figma.com/v1/files/${fileKey}?depth=1`,
    { headers: { 'X-Figma-Token': token } }
  ).then(r => r.json());

  console.log(`File: ${meta.name}, Pages: ${meta.document.children.length}`);

  // 2. Fetch each page's content individually
  const results = [];
  for (const page of meta.document.children) {
    console.log(`Fetching page: ${page.name} (${page.id})`);

    const pageData = await fetch(
      `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${page.id}`,
      { headers: { 'X-Figma-Token': token } }
    ).then(r => r.json());

    results.push({ pageId: page.id, pageName: page.name, data: pageData });

    // Respect rate limits between page fetches
    await new Promise(r => setTimeout(r, 500));
  }

  return results;
}

## Figma API Support Request

**Account email:** [your-email]
**Plan tier:** [Starter/Professional/Organization/Enterprise]
**Endpoint:** [e.g., GET /v1/files/:key]
**File key:** [file key, not sensitive]

### Issue Description
[1-2 sentences describing the problem]

### Reproduction Steps
1. Call `GET https://api.figma.com/v1/files/FILE_KEY?depth=1`
2. Observe: [expected vs actual behavior]

### Diagnostic Data
- HTTP status: [status code]
- Response headers: [relevant headers, especially rate limit]
- Response time: [from curl timing]
- Frequency: [every time / intermittent / specific conditions]

### Request/Response (redacted)


### Environment
- Node.js: [version]
- OS: [os]
- Region: [your server region]
- Behind proxy: [yes/no]

Issue	Diagnostic	Solution
Intermittent 500s	Track frequency and timing	Log every request; report pattern to Figma
Slow responses	curl timing breakdown	Check if DNS/TLS is the bottleneck
Null image renders	Validate node visibility	Check node opacity and visibility in Figma
Memory crash	Large file JSON	Use `depth=1` + per-page `/nodes` calls

curl -sv -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1" 2>&1 \
  | /usr/bin/grep -E '^< (HTTP|retry-after|x-)'

< HTTP/2 429
< retry-after: 47

curl -s -o /dev/null -w '%{size_download}\n' -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}"
# 48731210   ← 48 MB full tree; switch to ?depth=1 + /nodes?ids=