# Reported issues for figma-mcp-express

Pod holds 13 of 13 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [figma-mcp-express](/mcp/figma-mcp-express).

## Most discussed

### get_design_context ignores nodeId parameter — returns current selection instead

## Symptom

When `get_design_context` is called with a `nodeId` parameter specifying a target node, it returns the design context for the current Figma selection instead of the specified node.

## Impact

Agents querying a specific component by ID receive data for whatever is currently selected in Figma, leading to incorrect structural reads and misidentified properties. Caused multiple debugging cycles in PickleHub build sessions.

## Steps to Reproduce

1. Have node A selected in Figma
2. Call

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/34) · 2026-06-17 · closed · 2 comments

### find_replace_text ignores nodeId scope — traverses entire page and component tree

## Symptom

`find_replace_text` is called with a `nodeId` parameter to scope the replacement to a specific frame, but the implementation traverses the entire page and component tree, hitting unintended nodes.

## Impact

In 2 separate production builds (PickleHub mobile app), this corrupted tab bar labels globally — replacing text in the target frame also replaced the same string in the master component and every other instance on the page. Required manual batch revert to restore.

## Steps to R

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/33) · 2026-06-17 · closed · 2 comments

### import_component_by_key (and batch writes) can hang with no timeout/cancellation — wedges the whole channel and collateral-kills concurrent agents

## Summary

`import_component_by_key` (and other plugin-side write ops) can **hang indefinitely with no timeout, no progress signal, and no cancellation**. Because each channel is a single serialized queue, a hung import **head-of-line-blocks every queued op on that channel**, and if the plugin actually disconnects mid-import it takes down **every agent sharing that channel** (one shared single-thread = one failure domain).

## Observed (real incident)

- Building a 14-screen mobile app, 3–4 con

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/31) · 2026-06-17 · closed · 2 comments

### Expose mainComponentId on instance reads (and list orphaned local masters) — recovery path for file-local component reuse

## Problem
Reusing a **file-local, unpublished** component (a registered organism like a custom BottomTabBar) across the same file is unreliable:
- `create_instance` **requires `componentId`** (the master NODE id) — `componentKey` alone errors `missing required param "componentId"`.
- The master **node id is not exposed by any read**: `get_node`/`get_nodes_info` on an instance return only `mainComponent:{key,name,remote:false}` (no id); `get_local_components` (per-page + all pages) does not list

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/29) · 2026-06-17 · closed · 2 comments

### save_screenshots: surface a per-item error reason instead of a silent {succeeded:0,total:0}

## Problem
During a multi-agent build session, `save_screenshots` repeatedly returned `{succeeded:0, total:0}` (or `failed:0` with nothing written) **without an error message**, across multiple agents/frames on the same channel. Agents had to fall back to the `get_screenshot` batch op (base64) to see their work.

## Impact
- Builders/reviewers silently get no image file; self-eval + visual verification break.
- No signal to distinguish "path write failed" from "node not found" from "plugin busy"

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/28) · 2026-06-17 · closed · 2 comments

### feat: support scroll/overflow and fixed-position settings via batch API

## Problem

Two frame/node properties critical for mobile prototype fidelity cannot be set via the batch API:

1. **`overflowDirection`** (`VERTICAL` / `HORIZONTAL` / `BOTH` / `NONE`) — controls whether a frame scrolls in the prototype. Currently read-only from the API; must be set manually in Figma UI (Design panel → Clip content + Prototype panel → Overflow behavior).

2. **`scrollBehavior`** (`SCROLLS` / `FIXED`) — controls whether a child node scrolls with its parent or stays pinned ("Fix po

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/38) · 2026-06-17 · closed · 1 comment

### get_batch_op_spec returns 0 results for valid existing ops (set_text, set_opacity, etc.)

## Symptom

`get_batch_op_spec` returns empty results or errors for ops that definitely exist in the batch catalog (e.g., `set_text`, `set_opacity`).

## Impact

Agents cannot validate op parameter schemas at runtime before building batch payloads. This leads to:
- Guessing parameter names (causing trial-and-error loops)  
- 120+ `get_batch_op_spec` calls across 9 agent sessions with unreliable results
- Agents falling back to `search_batch_ops` + reading skill docs for every write

## Observed 

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/36) · 2026-06-17 · closed · 1 comment

### create_variable batch op: validation fails even when required 'type' field is present

## Symptom

The `create_variable` batch op rejects payloads with error "missing string `type`" even when the `type` field is explicitly present in the payload.

## Impact

Agents cannot create new design variables through the batch API. They fall back to reusing existing variables or abandoning the variable creation step entirely.

## Example Payload (fails)

```json
{
  "type": "create_variable",
  "params": {
    "name": "spacing/custom",
    "type": "FLOAT",
    "collectionId": "VariableColle

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/35) · 2026-06-17 · closed · 1 comment

## Most recent

### batch text values: `$`+digit collides with op-ref syntax (e.g. "$12.2B" parsed as ref to op #12)

Inside a `batch(ops:[...])` call, a text value containing `$` immediately followed by digits — e.g. `set_text` with `"$12.2B"` or `create_text` `"$2.5B revenue"` — is parsed by the op-ref resolver as a reference to another op in the batch (`$12` → "ref points to op #12"), and the build fails.

## Impact
Any dollar-denominated copy in a batch fails. This is common in finance/IR/pricing decks. The only stopgap found is inserting a zero-width space (U+200B) between `$` and the first digit so the ad

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/82) · 2026-06-26 · open · 0 comments

### A plugin disconnect on a shared channel is a single failure domain — one op's drop kills every concurrent agent (failure isolation + reconnect resilience)

## Summary

A channel is backed by a single plugin WebSocket on one shared thread, so it is **one failure domain**: when the plugin disconnects mid-op (e.g. a hung `import_component_by_key`, a plugin crash, a transient socket drop), **every agent sharing that channel dies** — including agents that were only *reading* and had nothing to do with the failing op. There is no per-request isolation and no in-flight survival across a reconnect.

This is the resilience/blast-radius half of #31. #31 asks

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/32) · 2026-06-17 · open · 1 comment

### Can't override a component INSTANCE's auto-layout (alignment/padding) — set_auto_layout rejects instances ('not a FRAME')

## Problem
`set_auto_layout` errors `Node <id> is not a FRAME` when the target is an INSTANCE. So you cannot override a component instance's auto-layout properties — `primaryAxisAlignItems`, `counterAxisAlignItems`, padding, itemSpacing — even though the Figma API allows these overrides on instances.

## Concrete impact
A kit Solid Button instance bottom-aligns its label (`counterAxisAlignItems=MAX` in the master), so the text renders a few px below the button's vertical center. The natural fix 

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/30) · 2026-06-17 · closed · 1 comment

### Reads don't surface fill/paint variable bindings — token-binding unverifiable (only effects show boundVariables)

## Problem
No read tool surfaces a **fill/paint** variable binding. A variable-bound fill and a hand-typed raw hex of the same value are byte-identical in every read output, so there's no way to verify whether an authored fill is bound to a design token.

- `get_node` / `get_nodes_info` flatten every fill to a resolved hex array (`fills:["#ffffff"]`), no `boundVariables`.
- `get_design_context` at **every** detail (`compact`/`full`/`codegen`) serializes fills only as resolved-hex dedup aliases i

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/27) · 2026-06-17 · closed · 1 comment

### Version-aware leader election: prevent a stale binary from leading port 1994

## Background

figma-mcp-express elects a single **leader** on port 1994; other instances become **followers** that forward RPCs to the leader (`internal/election.go`, `internal/leader.go`, `internal/node.go`). When several instances of **different versions** run concurrently (mixed dev/published binaries, leftover processes from other sessions, the CC plugin's `npx` server racing a local build), whichever binds the port first wins — even if it's an **older** binary.

A follower then forwards a 

[Read the thread](https://github.com/sunhome243/figma-mcp-express/issues/26) · 2026-06-16 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/sunhome243/figma-mcp-express/issues).