Figma MCP troubleshooting
This is the FigmaMCP troubleshooting hub. Find what you see in the table, read the error code your agent returned, and follow the recovery. Most problems come from an agent started before setup, a plugin that is not open, or a file set to read-only.
Symptom to fix
FigmaMCP returns structured errors. Each one comes from a fixed rule, so a retry with the same input gives the same result. Change the condition first.
| Symptom | Likely error code | What to do | Page |
|---|---|---|---|
| The agent has no Figma tools | None | Restart Claude Code or Codex so it loads the tool. | Not working |
| FigmaMCP is missing from Plugins, Development | None | Open the FigmaMCP Mac app and click Add to Figma. Use the desktop app, not the browser. | Plugin not showing |
| No plugin is connected | PLUGIN_PEER_UNAVAILABLE | Ask the user to open the plugin in the file, then retry or call channel_join with a link. | Not working |
| The agent asks which file | CHANNEL_NOT_BOUND | Call channel_join with a Figma link to the file the user means. details.channels lists the open files. | Not working |
| The agent reads but cannot edit | READ_ONLY_MODE | Inform the user. Only read tools work until the user turns on AI can edit this file in the plugin. | Not working |
| The target layer is outside the allowed area | OUTSIDE_SCOPE | Do not retry with the same ID. Pick a node inside the scope, or ask the user to reconnect with a broader scope. | Is it safe |
| The layer name does not match | NAME_MISMATCH | Call node_info to refresh, then retry with the actual name. | Not working |
| Variable or style edits are refused | VARIABLE_EDITS_DISABLED, STYLE_EDITS_DISABLED | Inform the user. Ask them to reconnect with that editing enabled. | Variables |
| The plugin closed during a command | PLUGIN_DISCONNECTED | Reopen the plugin. Check with node_info whether the edit applied before you repeat it. | Not working |
| The server and plugin versions differ | VERSION_MISMATCH | Server older: reconnect FigmaMCP in the AI app (Claude Code: /mcp) or start a new session. Plugin older: close and reopen the FigmaMCP panel. | Not working |
channel_join waits, then fails | CONNECTION_NOT_READY | Open the FigmaMCP app and the plugin, then retry. Calling page_info also binds to the open plugin. | Not working |
| The plugin is open twice | PLUGIN_PEER_AMBIGUOUS | In Figma, close or disconnect the duplicate instance. Leave exactly one plugin connected. | Plugin not showing |
| A variable delete is refused | VARIABLE_IN_USE | Read each consumer, clear or rebind it, then retry the exact deletion. | Variables |
| An error says the edit may be half done | details.partialMutation: true | Do not retry yet. Read details.whatChanged and details.before, check the IDs with node_info, and reconcile first. | Is it safe |
A scope refusal can arrive as UNKNOWN_ERROR with an Operation Denied message, and NAME_MISMATCH arrives as UNKNOWN_ERROR with the text nodeName does not match name of nodeId. Match on the message, not only the code.
Where to start
FigmaMCP has two detail pages: Figma MCP not working for connection errors and refused edits, and Plugin not showing in Figma for a missing plugin. FigmaMCP runs only on macOS, needs the Figma desktop app and is not on Figma Community.
Still stuck?
Still stuck? File an issue with your macOS and Figma app versions and the exact error. Do not include private design content.
Download for Mac Version 0.1.20 macOS 14+ · Intel & Apple Silicon · ~155 MB
Related: Not working · Plugin not showing · Setup · How it works
Questions
Why does a retry give the same error?
Do I need to reinstall when something fails?
What does partialMutation mean?
Last updated: