---

name: figma-debug-bundle description: 'Collect Figma API diagnostic evidence for support tickets and troubleshooting.

Use when encountering persistent issues, preparing support tickets,

or collecting diagnostic information for Figma API problems.

Trigger with phrases like "figma debug", "figma support bundle",

"collect figma logs", "figma diagnostic".

' allowed-tools: Read, Bash(curl:), Bash(tar:), Bash(node:*), Grep version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• figma compatibility: Designed for Claude Code

---

Figma Debug Bundle

Overview

Collect all diagnostic data needed to troubleshoot Figma REST API issues or submit a support request. Outputs a redacted archive with connectivity tests, token validation, rate limit status, and API response samples.

Prerequisites

• FIGMA_PAT environment variable set
• curl and jq available
• A Figma file key to test against

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# figma-debug-bundle.sh
set -euo pipefail

BUNDLE_DIR="figma-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== Figma Debug Bundle ===" | tee "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "---" >> "$BUNDLE_DIR/summary.txt"

# 1. Environment info
echo "--- Environment ---" >> "$BUNDLE_DIR/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -srm)" >> "$BUNDLE_DIR/summary.txt"
echo "PAT configured: ${FIGMA_PAT:+YES (${#FIGMA_PAT} chars)}" >> "$BUNDLE_DIR/summary.txt"
echo "File key: ${FIGMA_FILE_KEY:-NOT SET}" >> "$BUNDLE_DIR/summary.txt"

# 2. API connectivity test
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
echo -n "GET /v1/me: " >> "$BUNDLE_DIR/summary.txt"
curl -s -o "$BUNDLE_DIR/me.json" -w "%{http_code} %{time_total}s" \
  -H "X-Figma-Token: ${FIGMA_PAT}" \
  https://api.figma.com/v1/me >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# 3. File access test (if key is set)
if [ -n "${FIGMA_FILE_KEY:-}" ]; then
  echo -n "GET /v1/files: " >> "$BUNDLE_DIR/summary.txt"
  curl -s -o "$BUNDLE_DIR/file-meta.json" -w "%{http_code} %{time_total}s" \
    -H "X-Figma-Token: ${FIGMA_PAT}" \
    "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}?depth=1" >> "$BUNDLE_DIR/summary.txt"
  echo "" >> "$BUNDLE_DIR/summary.txt"
fi

# 4. Rate limit check (capture response headers)
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Rate Limit Headers ---" >> "$BUNDLE_DIR/summary.txt"
curl -s -D "$BUNDLE_DIR/headers.txt" -o /dev/null \
  -H "X-Figma-Token: ${FIGMA_PAT}" \
  https://api.figma.com/v1/me
grep -iE "(rate|retry|figma)" "$BUNDLE_DIR/headers.txt" >> "$BUNDLE_DIR/summary.txt" 2>/dev/null || echo "No rate limit headers" >> "$BUNDLE_DIR/summary.txt"

# 5. Redact sensitive data
echo "" >> "$BUNDLE_DIR/summary.txt"
echo "--- Redaction ---" >> "$BUNDLE_DIR/summary.txt"
# Remove email from /v1/me response
if [ -f "$BUNDLE_DIR/me.json" ]; then
  jq '{handle: .handle, id: .id, img_url: "[REDACTED]", email: "[REDACTED]"}' \
    "$BUNDLE_DIR/me.json" > "$BUNDLE_DIR/me-redacted.json" 2>/dev/null || true
  rm -f "$BUNDLE_DIR/me.json"
fi

# Remove raw headers (may contain token in other tools)
rm -f "$BUNDLE_DIR/headers.txt"

echo "Redaction complete" >> "$BUNDLE_DIR/summary.txt"

# 6. Package
tar -czf "$BUNDLE_DIR.tar.gz" "$BUNDLE_DIR"
rm -rf "$BUNDLE_DIR"
echo "Bundle created: $BUNDLE_DIR.tar.gz"

Step 2: Run the Bundle

chmod +x figma-debug-bundle.sh
./figma-debug-bundle.sh

Step 3: Review Before Sharing

# Inspect the bundle contents
tar -tzf figma-debug-*.tar.gz
# Extract and review
tar -xzf figma-debug-*.tar.gz
cat figma-debug-*/summary.txt

Output

• figma-debug-YYYYMMDD-HHMMSS.tar.gz containing:
  • summary.txt -- environment, connectivity, rate limit status
  • me-redacted.json -- authenticated user (email redacted)
  • file-meta.json -- file metadata (if file key provided)

Error Handling

Item	What It Catches	Why It Matters
/v1/me response code	Token validity	403 = expired/invalid PAT
/v1/files response code	File access	404 = wrong key, 403 = not shared
Rate limit headers	Throttling state	Retry-After shows if currently limited
Response time	Latency issues	>2s suggests network or server problems

Examples

ALWAYS REDACT Before Sharing

• Personal access tokens (figd_*)
• Email addresses
• OAuth client secrets
• File content (unless relevant to the bug)

Safe to Include

• HTTP status codes and response times
• Error message text
• Node IDs and file keys (not secrets)
• Rate limit header values

Resources

• Figma Support
• Figma Status Page
• Figma Developer Forum

Next Steps

For rate limit issues, see figma-rate-limits.