FigmaMCP

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.

FigmaMCP symptoms, error codes and recoveries
SymptomLikely error codeWhat to doPage
The agent has no Figma toolsNoneRestart Claude Code or Codex so it loads the tool.Not working
FigmaMCP is missing from Plugins, DevelopmentNoneOpen the FigmaMCP Mac app and click Add to Figma. Use the desktop app, not the browser.Plugin not showing
No plugin is connectedPLUGIN_PEER_UNAVAILABLEAsk the user to open the plugin in the file, then retry or call channel_join with a link.Not working
The agent asks which fileCHANNEL_NOT_BOUNDCall 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 editREAD_ONLY_MODEInform 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 areaOUTSIDE_SCOPEDo 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 matchNAME_MISMATCHCall node_info to refresh, then retry with the actual name.Not working
Variable or style edits are refusedVARIABLE_EDITS_DISABLED, STYLE_EDITS_DISABLEDInform the user. Ask them to reconnect with that editing enabled.Variables
The plugin closed during a commandPLUGIN_DISCONNECTEDReopen the plugin. Check with node_info whether the edit applied before you repeat it.Not working
The server and plugin versions differVERSION_MISMATCHServer 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 failsCONNECTION_NOT_READYOpen the FigmaMCP app and the plugin, then retry. Calling page_info also binds to the open plugin.Not working
The plugin is open twicePLUGIN_PEER_AMBIGUOUSIn Figma, close or disconnect the duplicate instance. Leave exactly one plugin connected.Plugin not showing
A variable delete is refusedVARIABLE_IN_USERead each consumer, clear or rebind it, then retry the exact deletion.Variables
An error says the edit may be half donedetails.partialMutation: trueDo 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?
FigmaMCP errors come from fixed rules inside the plugin. Change the condition first, for example open the plugin, turn on the edit switch or refresh the layer name with node_info.
Do I need to reinstall when something fails?
Usually not. Check that your agent was restarted after setup, that the plugin is open in the file, and that AI can edit this file is on.
What does partialMutation mean?
An error with details.partialMutation set to true means a change may have survived a failed step. Do not retry yet. Read whatChanged and before, check the IDs with node_info, and fix the state first.

Last updated: