🔧 Troubleshooting Guide

Comprehensive solutions for common issues

MCP Connection Issues
Docker Issues
Analysis Failures
Component Rendering
Images & Assets
Fonts & Typography
CSS & Styling
Performance Issues
API Errors

MCP Connection Issues

🔴 MCP Disconnected in Dashboard

Symptoms:

Red "MCP Disconnected" indicator in dashboard
Analysis fails with "Cannot connect to MCP server"

Causes & Solutions:

1. Figma Desktop Not Running

# Check if Figma Desktop is running
ps aux | grep Figma  # macOS
tasklist | findstr Figma  # Windows

# Solution: Start Figma Desktop application

2. MCP Server Not Started

# Verify MCP server is accessible
curl http://localhost:3845/mcp

# Expected: HTTP response (even 400 error means server is responding)
# Error: Connection refused = server not running

Fix:

Open Figma Desktop
Ensure MCP server is enabled in Figma settings
Check Figma Console for MCP server logs

3. Port 3845 Blocked

# Check if port is in use
lsof -i :3845  # macOS/Linux
netstat -ano | findstr :3845  # Windows

# If blocked by another process:
# 1. Stop that process
# 2. Restart Figma Desktop

4. Docker Network Issues

# Test from Docker container
docker exec mcp-figma-v1 wget -O- http://host.docker.internal:3845/mcp

# If fails, check docker-compose.yml:
extra_hosts:
  - "host.docker.internal:host-gateway"  # Must be present

Fix:

# Rebuild Docker network
docker-compose down
docker-compose up --build

5. Firewall Blocking Connection

macOS:

# Check firewall settings
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# Allow Docker
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /Applications/Docker.app

Windows:

# Check Windows Firewall
Get-NetFirewallRule | Where-Object {$_.DisplayName -like "*Docker*"}

# Allow Docker through firewall
New-NetFirewallRule -DisplayName "Docker Desktop" -Direction Inbound -Action Allow

Docker Issues

Container Won't Start

Error: Cannot connect to Docker daemon

# 1. Start Docker Desktop
open -a Docker  # macOS
# Or launch Docker Desktop from Start menu (Windows)

# 2. Wait for Docker to fully start (whale icon in system tray)

# 3. Verify Docker is running
docker ps

# 4. Try starting containers
docker-compose up

Port Already in Use

Error: Bind for 0.0.0.0:5173 failed: port is already allocated

# Find process using port 5173
lsof -i :5173  # macOS/Linux
netstat -ano | findstr :5173  # Windows

# Kill process
kill -9 <PID>  # macOS/Linux
taskkill /PID <PID> /F  # Windows

# Or change port in docker-compose.yml
ports:
  - "5174:5173"  # Use different port

Volume Mount Issues

Symptoms:

Hot reload not working
Changes not reflected in container

# Check volume mounts
docker inspect mcp-figma-v1 | grep Mounts -A 20

# Verify paths exist on host
ls -la ./src
ls -la ./scripts

# Rebuild with fresh volumes
docker-compose down -v
docker-compose up --build

Container Crashes on Startup

# Check logs
docker logs mcp-figma-v1

# Common causes:

# 1. Missing node_modules in container
docker exec mcp-figma-v1 ls /app/node_modules
# Fix: Rebuild container to reinstall dependencies
docker-compose down
docker-compose up --build
# Or install inside running container:
docker exec mcp-figma-v1 npm install --legacy-peer-deps

# 2. Syntax errors
docker exec mcp-figma-v1 npm run lint
# Fix: Fix linting errors in code

# 3. Missing environment variables
docker exec mcp-figma-v1 env
# Fix: Add to docker-compose.yml

# 4. Chromium not found (for Puppeteer)
docker exec mcp-figma-v1 which chromium
# Fix: Rebuild image (should install Chromium)

Out of Disk Space

# Check Docker disk usage
docker system df

# Clean up
docker system prune -a  # Remove unused images/containers
docker volume prune     # Remove unused volumes

# Free space in Docker Desktop settings (macOS)
# Preferences → Resources → Disk Image Size

Analysis Failures

Analysis Starts but Never Completes

Symptoms:

Logs stop mid-analysis
No error message
Status remains "in progress"

Common Causes:

1. Figma API Rate Limit

# Check usage bar in dashboard
# If >80% usage: Wait before retrying

# Workaround: Reduce chunk count
# Edit metadata.xml to limit child nodes

2. Node.js Process Crash

# Check container logs
docker logs mcp-figma-v1

# Look for: "out of memory", "segmentation fault"

# Fix: Increase Docker memory
# Docker Desktop → Preferences → Resources → Memory
# Set to 4GB or higher

3. Network Timeout

# Increase timeout in figma-cli.js
const timeout = 60000  // 60 seconds

# Or retry analysis

Invalid Figma URL

Error: Invalid Figma URL format

Valid Formats:

✅ https://www.figma.com/design/ABC123?node-id=1-2
✅ https://www.figma.com/file/ABC123?node-id=1-2
✅ https://www.figma.com/design/ABC123/Page-Name?node-id=1-2

❌ https://www.figma.com/ABC123
❌ figma.com/design/ABC123
❌ https://www.figma.com/design/ABC123 (missing node-id)

Extract from Figma:

Select layer in Figma
Right-click → "Copy link to selection"
Paste into dashboard

Node Not Found

Error: Node 123:456 not found

Causes:

Node deleted in Figma
Wrong file ID
Wrong node ID
Insufficient permissions

Fix:

# 1. Verify node exists in Figma
# Open Figma file, check layer exists

# 2. Get fresh URL
# Right-click layer → "Copy link to selection"

# 3. Check file permissions
# Ensure you have view access to Figma file

Chunk Extraction Fails

Error: Failed to extract chunk: Header

Note: Chunking only activates when design is large/complex. Small designs use Simple Mode (no chunks).

# Check MCP server logs in Figma Console

# Common causes:

# 1. Node too complex (>1000 elements)
# Fix: Simplify design or split into smaller pieces

# 2. Invalid characters in layer name
# Fix: Rename layer in Figma (avoid: /, \, :, *, ?, ", <, >, |)

# 3. Nested components too deep
# Fix: Flatten component instances

# 4. Design might work in Simple Mode
# If design is small, it won't use chunks at all

Component Rendering

Component Won't Load in Dashboard

Symptoms:

Preview tab shows error
"Cannot find module" in console

# 1. Check file exists
ls src/generated/export_figma/node-*/Component-fixed.tsx

# 2. Check for syntax errors
docker exec mcp-figma-v1 npm run lint

# 3. Check browser console (F12)
# Look for import errors

# 4. Verify CSS exists
ls src/generated/export_figma/node-*/Component-fixed.css

Fix:

# Re-run processing
docker exec mcp-figma-v1 node scripts/unified-processor.js \
  src/generated/export_figma/node-{id}/Component.tsx \
  src/generated/export_figma/node-{id}/Component-fixed.tsx \
  src/generated/export_figma/node-{id}/metadata.xml

Component Renders Incorrectly

Symptoms:

Layout broken
Elements misaligned
Wrong colors/sizes

Debugging Steps:

Compare with Figma Screenshot

# Open report.html
open src/generated/export_figma/node-*/report.html

Check Transform Stats

# View analysis.md
cat src/generated/export_figma/node-*/analysis.md

Inspect Generated Code

# Check Component-fixed.tsx
cat src/generated/export_figma/node-*/Component-fixed.tsx

Test Individual Chunks

# Check chunks-fixed/
ls src/generated/export_figma/node-*/chunks-fixed/

Common Issues:

Issue	Cause	Fix
Overlapping elements	Absolute positioning	Check position-fixes transform
Missing background	Gradient not applied	Check post-fixes transform
Wrong font	Font not loaded	Check font-detection transform
Misaligned items	Flexbox issue	Check auto-layout transform

Blank Preview

Causes:

CSS Not Loaded

# Check network tab (F12)
# Look for 404 on .css files

React Errors

# Check console (F12)
# Look for React errors

Vite Build Issues

# Restart Vite server
docker-compose restart

Images & Assets

Images Not Appearing

Symptoms:

Broken image icons
Images show as 404

Debugging:

# 1. Check img/ directory exists
ls src/generated/export_figma/node-*/img/

# 2. Check images have proper names (not hashes)
# ✅ logo.png
# ❌ a1b2c3d4e5f6.png

# 3. Check metadata.xml has layer names
cat src/generated/export_figma/node-*/metadata.xml | grep name=

Fix:

# Re-organize images
docker exec mcp-figma-v1 node scripts/post-processing/organize-images.js \
  src/generated/export_figma/node-{id}

If still failing:

# 1. Check tmp/figma-assets/ has images
ls tmp/figma-assets/

# 2. If empty, MCP didn't download images
# Check MCP parameters in cli/config/figma-params.json:
{
  "commonParams": {
    "renderImages": true,  // Must be true
    "dirForAssetWrites": "/app/tmp/figma-assets"
  }
}

# 3. Re-run analysis

SVG Icons Broken

Symptoms:

SVG elements not displaying
Console errors about SVG

Common Causes:

Nested SVG Elements

# Check if svg-consolidation transform is enabled
grep "svg-consolidation" scripts/config.js

Invalid Attributes

# Check if svg-icon-fixes transform is enabled
grep "svg-icon-fixes" scripts/config.js

CSS Variables in Paths

# Run fix-svg-vars script
docker exec mcp-figma-v1 node scripts/post-processing/fix-svg-vars.js \
  src/generated/export_figma/node-{id}

Fonts & Typography

Custom Fonts Not Loading

Symptoms:

Text renders in fallback font
Google Fonts not applied

Debugging:

# 1. Check Component-fixed.css has Google Fonts import
head -n 10 src/generated/export_figma/node-*/Component-fixed.css

# Expected:
# @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap');

Fix if Missing:

# 1. Check variables.json
cat src/generated/export_figma/node-*/variables.json | grep Font

# 2. Re-run processing with font-detection enabled
grep "font-detection" scripts/config.js
# Should show: { enabled: true }

Network Issues:

# Check if Google Fonts is accessible
curl "https://fonts.googleapis.com/css2?family=Inter:wght@400;600"

# If blocked, use self-hosted fonts

Font Weights Incorrect

Symptoms:

Text too thin or too bold
Font weight doesn't match Figma

Check Mapping:

// font-detection.js
const styleMap = {
  'Thin': 100,
  'ExtraLight': 200,
  'Light': 300,
  'Regular': 400,
  'Medium': 500,
  'SemiBold': 600,
  'Bold': 700,
  'ExtraBold': 800,
  'Black': 900
}

Verify in Code:

# Check inline styles
grep "fontWeight" src/generated/export_figma/node-*/Component-fixed.tsx

CSS & Styling

Tailwind Classes Not Applied

Symptoms:

Components render unstyled
Tailwind classes visible but not working

Cause: Arbitrary values not in safelist

Fix:

Use Component-clean.tsx Instead

# Re-run with --clean flag
./cli/figma-analyze "URL" --clean

# Use Component-clean.tsx (pure CSS, no Tailwind)

Or Add Safelist to Tailwind Config

// tailwind.config.js
module.exports = {
  safelist: [
    { pattern: /.*/ }  // Allow all classes (not recommended for production)
  ]
}

CSS Variables Not Resolved

Symptoms:

Styles show var(--variable-name) instead of values

Check Transform:

# Ensure css-vars transform is enabled
grep "css-vars" scripts/config.js

# Should show: { enabled: true }

Verify Variables:

# Check variables.json exists and has data
cat src/generated/export_figma/node-*/variables.json

Re-run Processing:

docker exec mcp-figma-v1 node scripts/unified-processor.js \
  src/generated/export_figma/node-{id}/Component.tsx \
  src/generated/export_figma/node-{id}/Component-fixed.tsx \
  src/generated/export_figma/node-{id}/metadata.xml

Performance Issues

Slow Analysis

Symptoms:

Analysis takes >5 minutes
Container uses high CPU/memory

Optimizations:

Reduce Chunk Count

# Flatten layers in Figma
# Fewer child nodes = faster processing

Increase Docker Resources

Docker Desktop → Preferences → Resources
CPU: 4+ cores
Memory: 4+ GB

Disable Unnecessary Transforms

// scripts/config.js
export const defaultConfig = {
  'production-cleaner': { enabled: false },  // Disable for dev
  // ... enable only what you need
}

Dashboard Slow to Load

Symptoms:

Tests page takes long to load
Pagination laggy

Optimizations:

Reduce Tests Per Page

// ExportFigmasPage.tsx
const [perPage, setPerPage] = useState(6)  // Lower value

Delete Old Tests

# Delete old tests from dashboard
# Or manually:
rm -rf src/generated/export_figma/node-*-old-timestamp

Lazy Load Images

// Use loading="lazy" on images
<img src="..." loading="lazy" />

API Errors

500 Internal Server Error

# Check server logs
docker logs mcp-figma-v1

# Look for stack traces

# Common causes:

# 1. Missing file
# Fix: Verify all required files exist

# 2. Invalid JSON
# Fix: Validate metadata.json, variables.json

# 3. Permission denied
# Fix: Check file permissions
chmod -R 755 src/generated/export_figma/

404 Not Found

For API Endpoint:

# Verify route exists in server.js
grep "/api/your-endpoint" server.js

# Restart server
docker-compose restart

For Static File:

# Check file exists
ls src/generated/export_figma/node-*/filename

# Check Vite public directory
ls public/

SSE Connection Closed Prematurely

Symptoms:

Real-time logs stop updating
EventSource shows "error" state

# Check if analysis process crashed
docker logs mcp-figma-v1 | tail -50

# Increase SSE timeout in frontend
const eventSource = new EventSource(url)
eventSource.addEventListener('error', (e) => {
  console.error('SSE error:', e)
  // Implement retry logic
})

Page Reloads & HMR Issues

🔴 Page Reloads During Analysis

Symptoms:

Analysis starts successfully on /analyze page
Logs appear in real-time
Suddenly page refreshes mid-analysis
All logs disappear
Analysis completes but you can't see what happened

Cause:

Vite's HMR (Hot Module Replacement) detects new files being created in src/generated/export_figma/ and triggers a full page reload.

Solution:

This is already fixed in the current version via selective file watching in vite.config.js:

// vite.config.js
server: {
  watch: {
    ignored: [
      '**/src/generated/**/*.html',
      '**/src/generated/**/*.png',
      '**/src/generated/**/*.jpg',
      '**/src/generated/**/*.svg',
      '**/src/generated/**/*.json',
      '**/src/generated/**/*.xml',
      '**/src/generated/**/*.md',
      '**/src/generated/**/*.css',
    ]
  }
}

If you encounter this issue:

Verify vite.config.js has the ignored list:
```
grep -A 10 "watch:" vite.config.js
```
Restart Vite server:
```
docker-compose restart
```
Ensure .tsx/.jsx files are NOT in the ignored list (they need to be watched for dynamic imports)

🔴 DELETE Not Refreshing List

Symptoms:

Delete a test from the dashboard
DELETE API call succeeds (file deleted from disk)
Test still appears in the list
Need to manually refresh page or restart server to see deletion

Cause:

When watch.ignored is configured, Vite doesn't detect file deletions in src/generated/export_figma/. Components used to call window.location.reload(), which relied on Vite's cache, but Vite doesn't know the file was deleted.

Solution:

This is already fixed via callback-based refresh:

// ExportFigmaCard.tsx - DELETE handler
if (onRefresh) {
  onRefresh()  // Calls API to fetch fresh list
} else {
  window.location.reload()  // Fallback
}

If you encounter this issue:

Verify the component chain passes onRefresh:

# Check ExportFigmasPage passes reload to children
grep "onRefresh={reload}" src/components/pages/ExportFigmasPage.tsx

# Check ExportFigmaCard receives onRefresh prop
grep "onRefresh?" src/components/features/tests/ExportFigmaCard.tsx

Check useExportFigmas hook exposes reload:

grep "reload:" src/hooks/useExportFigmas.ts

Restart containers:
```
docker-compose restart
```

🔴 Dynamic Imports Failing on New Tests

Symptoms:

Analysis completes successfully
Old tests (created before recent changes) preview correctly
New tests (freshly created) show error: "Unknown variable dynamic import: ../../generated/export_figma/node-XXX/Component.jsx"
Error message: "Le composant est peut-être manquant ou invalide"

Cause:

If .tsx or .jsx files are added to watch.ignored, Vite stops watching AND transforming them. Old tests work because they were already transformed before the change. New tests fail because Vite never transforms them.

Solution:

CRITICAL: Never add .tsx or .jsx to the watch.ignored list.

Verify your vite.config.js:

// ❌ WRONG - Will break dynamic imports
ignored: [
  '**/src/generated/**'  // Too broad!
]

// ❌ WRONG - Will break dynamic imports
ignored: [
  '**/src/generated/**/*.tsx',  // Don't ignore .tsx!
  '**/src/generated/**/*.jsx',  // Don't ignore .jsx!
]

// ✅ CORRECT - Ignore only non-code files
ignored: [
  '**/src/generated/**/*.html',
  '**/src/generated/**/*.png',
  '**/src/generated/**/*.jpg',
  '**/src/generated/**/*.svg',
  '**/src/generated/**/*.json',
  '**/src/generated/**/*.xml',
  '**/src/generated/**/*.md',
  '**/src/generated/**/*.css',
]

If you made this mistake:

Fix vite.config.js - Remove .tsx and .jsx from ignored list
Restart Vite server:
```
docker-compose restart
```

Clear Vite cache (if needed):

docker exec mcp-figma-v1 rm -rf /app/node_modules/.vite
docker-compose restart

New tests should now work - Old tests will continue working

General Debugging Tips

Enable Verbose Logging

# Add DEBUG environment variable
docker-compose.yml:
  environment:
    - DEBUG=true

# Check logs
docker logs -f mcp-figma-v1

Reset Everything

# Nuclear option: Start fresh

# 1. Stop containers
docker-compose down -v

# 2. Remove generated files
rm -rf src/generated/export_figma/*
rm -rf tmp/*
rm -rf data/*

# 3. Rebuild
docker-compose build --no-cache
docker-compose up

Get Help

If issue persists:

Check GitHub Issues: Issues
Search Discussions: Discussions
Create New Issue:
- Include error message
- Include Figma URL (if public)
- Include Docker logs
- Include browser console logs
- Include system info (OS, Docker version)

Next Steps

See ARCHITECTURE.md for system design
See DEVELOPMENT.md for development workflow
See API.md for API documentation

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

🔧 Troubleshooting Guide

Table of Contents

MCP Connection Issues

🔴 MCP Disconnected in Dashboard

1. Figma Desktop Not Running

2. MCP Server Not Started

3. Port 3845 Blocked

4. Docker Network Issues

5. Firewall Blocking Connection

Docker Issues

Container Won't Start

Port Already in Use

Volume Mount Issues

Container Crashes on Startup

Out of Disk Space

Analysis Failures

Analysis Starts but Never Completes

1. Figma API Rate Limit

2. Node.js Process Crash

3. Network Timeout

Invalid Figma URL

Node Not Found

Chunk Extraction Fails

Component Rendering

Component Won't Load in Dashboard

Component Renders Incorrectly

Blank Preview

Images & Assets

Images Not Appearing

SVG Icons Broken

Fonts & Typography

Custom Fonts Not Loading

Font Weights Incorrect

CSS & Styling

Tailwind Classes Not Applied

CSS Variables Not Resolved

Performance Issues

Slow Analysis

Dashboard Slow to Load

API Errors

500 Internal Server Error

404 Not Found

SSE Connection Closed Prematurely

Page Reloads & HMR Issues

🔴 Page Reloads During Analysis

🔴 DELETE Not Refreshing List

🔴 Dynamic Imports Failing on New Tests

General Debugging Tips

Enable Verbose Logging

Reset Everything

Get Help

Next Steps