21 KiB
Part of the figma-generate-library skill.
Error Recovery Reference
Protocol for handling failures and incomplete runs across a 20–100+ call design system build.
1. Core Protocol: STOP → Inspect → Fix → Retry
use_figma is atomic — a failed script does not execute. If a script errors, no changes are made to the file. There are no partial nodes or half-built state from the failed call itself. Retrying after a fix is safe.
However, in multi-step workflows (20–100+ calls), previously successful calls will have created state that persists. If a workflow is abandoned mid-way, nodes from earlier successful calls remain in the file. The cleanup and idempotency patterns in this document handle that scenario.
The recovery sequence for a failed script:
1. STOP — Do not run any more use_figma writes.
2. INSPECT — Read the error message carefully. Optionally call get_metadata or get_screenshot to understand the current file state.
3. FIX — Correct the script that failed.
4. RETRY — Re-run the corrected script.
5. PERSIST — Update the state ledger with the outcome.
For abandoned multi-step workflows (where you need to roll back nodes from previous successful calls), use the cleanup protocol in Section 2.
2. sharedPluginData-Based Cleanup: Why Name Matching is Dangerous
Why name-prefix matching fails
A cleanup script that deletes "all nodes whose name starts with Button" will also delete nodes the user may have created manually with that name, or nodes from a previous approved phase. Name-based cleanup has no way to distinguish "orphan from a failed attempt" from "intentional user node."
Furthermore, variant names (Size=Medium, Style=Primary, State=Default) do not have consistent prefixes that are safe to target without also hitting legitimate nodes.
How setSharedPluginData / getSharedPluginData works
sharedPluginData is a key-value store attached to individual nodes. It persists across sessions and is invisible to the user in the Figma UI. Data is scoped by namespace — we use 'dsb'. Use three keys:
node.setSharedPluginData('dsb', 'run_id', 'ds-build-2024-001'); // identifies the build run
node.setSharedPluginData('dsb', 'phase', 'phase3'); // which phase created this node
node.setSharedPluginData('dsb', 'key', 'componentset/button');// unique logical key
// Reading:
const runId = node.getSharedPluginData('dsb', 'run_id'); // returns '' if never set
const key = node.getSharedPluginData('dsb', 'key');
getSharedPluginData returns '' (empty string, not null) for unset keys. Always check for !== ''.
Tag every created node immediately after creation — this enables safe cleanup if the multi-step workflow is abandoned later. Tag in the same statement sequence as creation:
const comp = figma.createComponent();
comp.setSharedPluginData('dsb', 'run_id', RUN_ID); // tag immediately
comp.setSharedPluginData('dsb', 'key', key); // tag immediately
// ... then do the rest of the setup
Complete cleanupOrphans script using run_id
This script finds all nodes tagged with a given run_id and optionally a phase filter, then removes them. Run it on the specific page where the failure occurred.
const TARGET_RUN_ID = 'ds-build-2024-001'; // run ID to clean
const TARGET_PHASE = 'phase3'; // optionally filter by phase ('' = all phases)
const PAGE_NAME = 'Button'; // page to clean (or null for all pages)
const pagesToSearch = PAGE_NAME
? [figma.root.children.find(p => p.name === PAGE_NAME)].filter(Boolean)
: figma.root.children;
const removed = [];
const skipped = [];
for (const page of pagesToSearch) {
await figma.setCurrentPageAsync(page);
const orphans = page.findAll(node => {
const runId = node.getSharedPluginData('dsb', 'run_id');
if (runId !== TARGET_RUN_ID) return false;
if (TARGET_PHASE && node.getSharedPluginData('dsb', 'phase') !== TARGET_PHASE) return false;
return true;
});
// Remove leaf-first to avoid removing parents before children
// Sort by depth (deepest first) to avoid double-remove errors
const sorted = orphans.slice().sort((a, b) => {
let depthA = 0, depthB = 0;
let n = a; while (n.parent) { depthA++; n = n.parent; }
n = b; while (n.parent) { depthB++; n = n.parent; }
return depthB - depthA;
});
for (const node of sorted) {
try {
if (node.removed) continue; // already removed (was a child of removed parent)
node.remove();
removed.push({ id: node.id, name: node.name, key: node.getSharedPluginData('dsb', 'key') });
} catch (e) {
skipped.push({ id: node.id, name: node.name, error: e.message });
}
}
}
return { removed: removed.length, skipped: skipped.length, details: removed };
After running cleanup, call get_metadata on the target page to confirm the orphaned nodes are gone before retrying.
3. Idempotency Patterns: Check-Before-Create
Run an idempotency check at the start of every create operation. If the entity already exists (tagged with the expected key), skip creation and return the existing ID.
Check-before-create for a variable collection
const KEY = 'collection/color';
const RUN_ID = 'ds-build-2024-001';
const COLLECTION_NAME = 'Color';
// Check: does a collection tagged with this key already exist?
const allCollections = await figma.variables.getLocalVariableCollectionsAsync();
// Variables/collections support sharedPluginData too — check by name as fallback
// Note: VariableCollection sharedPluginData is set via collection.setSharedPluginData(...)
const existing = allCollections.find(c =>
c.getSharedPluginData('dsb', 'key') === KEY
);
if (existing) {
return {
collectionId: existing.id,
modeIds: existing.modes.map(m => ({ name: m.name, id: m.modeId })),
alreadyExisted: true,
};
}
// Create fresh
const collection = figma.variables.createVariableCollection(COLLECTION_NAME);
collection.setSharedPluginData('dsb', 'run_id', RUN_ID);
collection.setSharedPluginData('dsb', 'key', KEY);
// Rename default mode, add second mode
collection.renameMode(collection.modes[0].modeId, 'Light');
const darkModeId = collection.addMode('Dark');
return {
collectionId: collection.id,
modeIds: [
{ name: 'Light', id: collection.modes[0].modeId },
{ name: 'Dark', id: darkModeId },
],
};
Check-before-create for a page
const KEY = 'page/button';
const PAGE_NAME = 'Button';
const RUN_ID = 'ds-build-2024-001';
// Check by sharedPluginData key first, then by name as fallback
let page = figma.root.children.find(p => p.getSharedPluginData('dsb', 'key') === KEY);
if (!page) {
page = figma.root.children.find(p => p.name === PAGE_NAME);
}
if (page) {
// Ensure it's tagged if it was found by name only
if (!page.getSharedPluginData('dsb', 'key')) {
page.setSharedPluginData('dsb', 'run_id', RUN_ID);
page.setSharedPluginData('dsb', 'key', KEY);
}
return { pageId: page.id, alreadyExisted: true };
}
page = figma.createPage();
page.name = PAGE_NAME;
page.setSharedPluginData('dsb', 'run_id', RUN_ID);
page.setSharedPluginData('dsb', 'key', KEY);
return { pageId: page.id, alreadyExisted: false };
Check-before-create for a component set
const KEY = 'componentset/button';
const PAGE_ID = 'PAGE_ID_FROM_STATE';
const RUN_ID = 'ds-build-2024-001';
const page = await figma.getNodeByIdAsync(PAGE_ID);
await figma.setCurrentPageAsync(page);
const existing = page.findAll(n =>
n.type === 'COMPONENT_SET' && n.getSharedPluginData('dsb', 'key') === KEY
);
if (existing.length > 0) {
return {
componentSetId: existing[0].id,
alreadyExisted: true,
};
}
// ... proceed with creation
return { componentSetId: null, alreadyExisted: false };
4. State Ledger
JSON Schema
Maintain a state ledger in your context (not in the Figma file) across calls. This is your source of truth for node IDs, completed steps, and pending validations.
{
"runId": "ds-build-2024-001",
"phase": "phase3",
"step": "component-button/combine-variants",
"completedSteps": [
"phase0",
"phase1/collections",
"phase1/primitives",
"phase1/semantics",
"phase2/pages",
"phase2/foundations-docs",
"phase3/component-avatar",
"phase3/component-icon"
],
"entities": {
"collections": {
"primitives": "VariableCollectionId:1234:5678",
"color": "VariableCollectionId:1234:5679",
"spacing": "VariableCollectionId:1234:5680"
},
"variables": {
"color/bg/primary": "VariableId:2345:1",
"color/bg/secondary": "VariableId:2345:2",
"color/bg/disabled": "VariableId:2345:3",
"color/text/on-primary": "VariableId:2345:4",
"color/text/on-secondary": "VariableId:2345:5",
"color/text/disabled": "VariableId:2345:6",
"spacing/sm": "VariableId:2345:7",
"spacing/md": "VariableId:2345:8",
"spacing/lg": "VariableId:2345:9",
"radius/md": "VariableId:2345:10"
},
"modes": {
"color/light": "2345:1",
"color/dark": "2345:2"
},
"pages": {
"Cover": "0:1",
"Foundations": "0:2",
"Button": "0:3"
},
"components": {
"Icon": "3456:1",
"Avatar": "3456:2",
"Button": "3456:3"
},
"componentSets": {
"Button": "4567:1"
}
},
"pendingValidations": [
"Button:metadata",
"Button:screenshot"
],
"userCheckpoints": {
"phase0": "approved-2024-01-15",
"phase1": "approved-2024-01-15",
"phase2": "approved-2024-01-15",
"component-avatar": "approved-2024-01-15"
}
}
Persisting between calls
After every successful use_figma call:
- Extract all IDs from the return value
- Add them to the appropriate
entitiessection of the ledger - Add the completed step to
completedSteps - Remove from
pendingValidationsif this call validated something - Update
phaseandstepto the current position
Rehydrating at session start
If a conversation is interrupted and resumed, read the state ledger and verify key entities still exist:
// Verify that critical nodes from the ledger still exist
const toVerify = {
'color-collection': 'VariableCollectionId:1234:5679',
'button-page': '0:3',
'button-componentset': '4567:1',
};
const results = {};
for (const [label, id] of Object.entries(toVerify)) {
const node = await figma.getNodeByIdAsync(id)
.catch(() => null);
results[label] = node ? { found: true, name: node.name } : { found: false };
}
return results;
If any entity is missing, treat the phase that created it as incomplete and re-run from that checkpoint.
5. Resume Protocol
Step 1: Inspect the file for run_id tags
const TARGET_RUN_ID = 'ds-build-2024-001';
const inventory = { pages: [], variables: [], componentSets: [], frames: [] };
// Scan pages
for (const page of figma.root.children) {
if (page.getSharedPluginData('dsb', 'run_id') === TARGET_RUN_ID) {
inventory.pages.push({ id: page.id, name: page.name, key: page.getSharedPluginData('dsb', 'key') });
}
}
// Scan variables
const allVars = await figma.variables.getLocalVariablesAsync();
for (const v of allVars) {
if (v.getSharedPluginData('dsb', 'run_id') === TARGET_RUN_ID) {
inventory.variables.push({ id: v.id, name: v.name, key: v.getSharedPluginData('dsb', 'key') });
}
}
// Scan all component sets and frames on each page
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
const nodes = page.findAll(n => n.getSharedPluginData('dsb', 'run_id') === TARGET_RUN_ID);
for (const n of nodes) {
if (n.type === 'COMPONENT_SET') {
inventory.componentSets.push({ id: n.id, name: n.name, key: n.getSharedPluginData('dsb', 'key') });
} else if (n.type === 'FRAME') {
inventory.frames.push({ id: n.id, name: n.name, key: n.getSharedPluginData('dsb', 'key') });
}
}
}
return inventory;
Step 2: Reconstruct state from inventory
Map the inventory keys back to the state ledger schema. For each entity found with a key, add its ID to the appropriate section. Mark the corresponding step as completedSteps.
Example mapping:
key: 'collection/color' → entities.collections.color
key: 'variable/color/bg/primary' → entities.variables['color/bg/primary']
key: 'page/button' → entities.pages.Button
key: 'componentset/button' → entities.componentSets.Button
Step 3: Identify the resume point
The resume point is the first step in the workflow that is NOT in completedSteps. If the inventory shows the Button component set exists but the pending validations list shows 'Button:screenshot', the resume point is the screenshot validation call, not re-creation.
Use the checkpoint table from the workflow to determine which phase to continue from:
Phase 0 complete: all planned pages listed in entities.pages
Phase 1 complete: all planned variables listed in entities.variables with correct scopes
Phase 2 complete: all structural pages + foundations doc frames present
Phase 3 complete (per component): componentSet exists + no pending validations + user checkpoint recorded
6. Failure Taxonomy
Recoverable Errors
These can be fixed and retried without affecting already-created entities:
| Category | Examples | Recovery |
|---|---|---|
| Layout errors | Variants stacked at (0,0), wrong padding values | Re-run the positioning step only |
| Naming issues | Typo in variant name, wrong casing | Find nodes by dsb_key, update name property |
| Missing property wiring | componentPropertyReferences not set |
Find component set by ID, re-run the property wiring step |
| Variable binding omission | A fill was hardcoded instead of bound | Find nodes by dsb_key, re-bind the fill |
| Wrong variable bound | Bound to wrong variable ID | Re-bind with correct variable ID |
| Text not visible | Font not loaded before text write | Re-run text creation with loadFontAsync first |
| Script timeout | Script exceeded time limit before completing | Script is atomic — nothing was created. Reduce scope (fewer nodes per call) and retry |
Structural Corruption (Requires Rollback or Restart)
These errors leave the file in a state where continuing forward is unreliable:
| Category | Examples | Recovery |
|---|---|---|
| Component cycle | A component instance was accidentally nested inside itself | Full cleanup of the affected component, restart that component from Call 1 |
| combineAsVariants with non-components | Mixed node types passed to combineAsVariants, causing unexpected merges | Remove the malformed component set, re-run from variant creation |
| Variable collection ID drift | Collection was deleted and re-created, old IDs in state ledger are stale | Re-run Phase 1 completely; update all IDs in state ledger |
| Page deletion | A page was deleted after component sets were created on it | Treat as Phase 2 incomplete; re-create the page + re-run affected component creations |
| Mode limit exceeded | addMode threw because the plan is Starter or Professional |
Redesign variable collection architecture to fit mode limits, restart Phase 1 |
Recovery from structural corruption: run cleanupOrphans for the entire run ID, then restart from the affected phase. Do NOT attempt to patch corrupted structure in-place.
7. Common Error Table
| Error message | Likely cause | Fix |
|---|---|---|
"Cannot create component from node" |
Tried to call createComponentFromNode on a node inside a component |
Create a fresh component instead: figma.createComponent() |
"in addMode: Limited to N modes only" |
Plan mode limit hit (Starter=1, Professional=4) | Redesign to use fewer modes or upgrade plan |
"setCurrentPageAsync: page does not exist" |
Page was deleted or wrong ID | Re-create the page using the idempotency pattern |
"Cannot read properties of null" |
getNodeByIdAsync returned null — node was deleted |
Run the resume protocol to find what exists, update state ledger |
"Expected nodes to be component nodes" |
Passed a non-ComponentNode to combineAsVariants |
Filter the array: nodes.filter(n => n.type === 'COMPONENT') |
"in createVariable: Cannot create variable" |
Collection was deleted or ID is wrong | Verify collection exists with getVariableCollectionByIdAsync |
"font not loaded" |
Called a text property setter without loadFontAsync first |
Add await figma.loadFontAsync({ family, style }) before the text operation |
"Cannot set properties of a read-only array" |
Tried to mutate fills/strokes in-place | Clone first: const fills = JSON.parse(JSON.stringify(node.fills)) |
"Expected RGBA color" |
Color value out of 0–1 range | Divide RGB 0–255 values by 255: { r: 65/255, g: 85/255, b: 143/255 } |
"Cannot add children to a non-parent node" |
Tried to append a child to a leaf node (text, rect) | Ensure the parent is a FrameNode, ComponentNode, or GroupNode |
"in combineAsVariants: nodes must be in the same parent" |
Components are on different pages | Move all components to the same page before combining |
"Script exceeded time limit" |
Loop creating too many nodes in one call | Split the work: create N/2 variants per call |
| Component set deletes itself | Tried to create a component set with no children | combineAsVariants requires at least 1 node — always pass 1+ |
addComponentProperty returns unexpected name |
This is normal — BOOLEAN/TEXT/INSTANCE_SWAP get #id:id suffix |
Save the returned key immediately and use that, not the input name |
8. Per-Phase Recovery Guidance
Phase 1 fails (variable creation)
Since use_figma is atomic, a failed call creates nothing. The most common scenario is that some calls in Phase 1 succeeded (creating some variables) while a later call failed.
Recovery steps:
- Run inspection script to find all variables tagged with your
run_id - Compare against the plan to identify which variables were successfully created and which are still missing
- If a successfully created variable has wrong values, call
variable.remove()and recreate it - Fix the failed script and retry — it's safe since the failed call created nothing
- Do NOT proceed to Phase 2 until ALL planned variables exist with correct scopes and code syntax
The most common Phase 1 failure: script timeout when creating many variables. Fix: batch variable creation — create at most 20–30 variables per call.
Phase 2 fails mid-execution (page/file structure)
Symptoms: some pages exist, others are missing; foundations doc frames are incomplete.
Recovery steps:
- Identify which pages were successfully created (check for
keytags) - Mark remaining pages as pending and create them in subsequent calls
- If a foundations doc frame is malformed, run
cleanupOrphansfordsb_phase: 'phase2'on that page, then recreate
Phase 2 failures rarely require Phase 1 rollback unless the page structure itself is corrupted (which is unusual).
Phase 3 fails (component creation)
This is the most common failure mode in long builds. Since use_figma is atomic, a failed call creates nothing — but previous successful calls in the component creation sequence will have created state. Handle by which call in the sequence failed:
If failure in Call 1 (page creation):
→ Nothing was created. Fix the script and retry.
If failure in Call 2 (doc frame):
→ Call 1's page exists. Fix Call 2 and retry — idempotency check handles it.
If failure in Call 3 (base component):
→ Calls 1-2 succeeded. Fix Call 3 and retry.
If failure in Call 4 (variant creation):
→ Call 3's base component exists. Fix Call 4 and retry.
→ If you need to restart from Call 3, clean up Call 3's nodes first
using cleanupOrphans scoped to the component page.
If failure in Call 5 (combineAsVariants + layout):
→ Variant ComponentNodes from Call 4 exist but aren't combined yet.
→ Fix Call 5 and retry.
→ If the component set was already created by a prior attempt of Call 5
that succeeded, remove it first, then re-run.
If failure in Call 6 (component properties):
→ The component set already exists and is structurally sound.
→ Fix Call 6 and retry — addComponentProperty is safe to retry if
you first check componentPropertyDefinitions for existing properties.
→ Idempotency check: if 'Label' property already exists, skip addComponentProperty.
Idempotency for component properties (Call 6 retry):
const existingDefs = cs.componentPropertyDefinitions;
const labelKey = existingDefs['Label']
? Object.keys(existingDefs).find(k => k.startsWith('Label'))
: cs.addComponentProperty('Label', 'TEXT', 'Button');
Phase 4 fails mid-execution (QA / Code Connect)
Phase 4 is non-destructive. Failures here do not corrupt Phase 3 work. Common failures:
- Accessibility audit finds contrast failures: do not attempt auto-fix. Report the specific variable IDs and token names that fail, then ask the user which value to update.
- Naming audit finds duplicates: list all duplicates with their
keyvalues, ask user which to keep, then remove the duplicates. - Code Connect mapping fails: treat as incomplete, not broken. Continue and leave as pending.