---
title: "Figma Code Connect API — Gotchas and Type Traps"
aliases: [code-connect-api, figma-plugin-api-gotchas]
tags: [figma, code-connect, plugin-api, gotcha]
created: 2026-05-15
updated: 2026-05-15
---

# Figma Code Connect API — Gotchas and Type Traps



Collected from writing `.figma.tsx` Code Connect files and iterating with the MCP. All of these fail silently or with opaque errors.

---

## 1. `findInstance()` Returns an `ErrorHandle` on Failure (Truthy!)

`figma.currentPage.findInstance(...)` returns an `ErrorHandle` object — **not `null`** — when no match is found. `ErrorHandle` is truthy, so `if (node)` always passes.

```ts
// BAD — ErrorHandle passes the truthy check
const node = figma.currentPage.findInstance({ ... })
if (node) {
  node.mainComponent  // TypeError: node.mainComponent is undefined
}

// GOOD — always check the type
if (node && node.type === 'INSTANCE') {
  // safe to use
}
```

---

## 2. `executeTemplate().example` Is `ResultSection[]`, Not a String

`figma.codeConnect.executeTemplate(node, template)` returns `{ example: ResultSection[] }`. If you concatenate it directly into a string you get `[object Object]`.

```ts
// BAD
const output = `<div>${result.example}</div>`  // → "<div>[object Object]</div>"

// GOOD — map sections to their text
const output = result.example.map(s => s.code ?? s.title ?? '').join('\n')
```

---

## 3. `hasCodeConnect()` Guard Before `executeTemplate()` Silently Drops Instances

`figma.codeConnect.hasCodeConnect(node)` returns `false` for components that have no Code Connect mapping in the current file. If you guard `executeTemplate()` behind `hasCodeConnect()`, you silently skip all non-connected instances instead of falling back to generated code.

```ts
// BAD — silently skips ~80% of instances
if (figma.codeConnect.hasCodeConnect(node)) {
  executeTemplate(node, ...)
}

// GOOD — call executeTemplate unconditionally; it handles missing mappings
const result = figma.codeConnect.executeTemplate(node, template)
// result.example will still contain generated fallback code
```

---

## 4. `getSlot()` vs `getInstanceSwap()` — Wrong Property Type

`figma.codeConnect.getSlot(prop)` only works for `SLOT` property type.  
`figma.codeConnect.getInstanceSwap(prop)` is required for `INSTANCE_SWAP` properties.

Using `getSlot()` on an `INSTANCE_SWAP` property returns `undefined` silently.

```ts
// Check property type first
const propType = node.componentPropertyDefinitions[propName].type

if (propType === 'SLOT') {
  return figma.codeConnect.getSlot(prop)
} else if (propType === 'INSTANCE_SWAP') {
  return figma.codeConnect.getInstanceSwap(prop)
}
```

---

## 5. `findInstance()` Requires `{ traverseInstances: true }` for Nested Layers

By default, `findInstance()` does not traverse into nested instances. If the target node is inside another instance, pass `traverseInstances: true`:

```ts
const node = figma.currentPage.findInstance({
  name: 'ButtonIcon',
  traverseInstances: true,   // ← required for nested layers
})
```

---

## 6. `path` Disambiguation When Siblings Share a Layer Name

If multiple siblings have the same layer name (common in design systems), `findInstance()` returns the first match. Use `path` to specify the parent:

```ts
const node = figma.currentPage.findInstance({
  name: 'Icon',
  path: ['CardContainer'],   // ← parent layer name narrows the search
  traverseInstances: true,
})
```

---

## 7. VARIANT Enum Mapping Must Be Exhaustive

When mapping a Figma VARIANT property to a code prop via `figma.widget.usePropertyMenu`, every possible variant value must be listed. Missing values silently produce `undefined`, which is then injected into JSX — no error thrown, malformed output.

```ts
// BAD — "Outline" variant not listed → produces undefined
figma.codeConnect.VARIANT('ButtonVariant', {
  'Default': 'primary',
  'Ghost': 'ghost',
  // 'Outline' missing → node with Outline variant → prop = undefined
})

// GOOD — enumerate all values
figma.codeConnect.VARIANT('ButtonVariant', {
  'Default': 'primary',
  'Ghost': 'ghost',
  'Outline': 'outline',   // ← exhaustive
})
```

**How to audit:** list all possible values of the Figma property via `node.componentPropertyDefinitions[propName].variantOptions` and cross-check against the VARIANT mapping.

---

## Related

- [[wiki/concepts/figma-code-connect-plan-requirements|figma-code-connect-plan-requirements]] — MCP vs CLI plan requirements
- [[wiki/concepts/figma-mcp-tools-reference|figma-mcp-tools-reference]] — full tool reference
- [[wiki/concepts/figma-skills-reference|figma-skills-reference]] — which skill to invoke for Code Connect
