Troubleshooting

Most problems come down to the connection. Start with whoami.

run whoami

It reports whether the plugin is connected, the pairing code, the open file and selection, the port, and any saved snapshots.

The dot stays grey

The plugin can't reach the server. Start your coding agent first so it starts the server, then run the plugin again. If you just ran setup, restart the agent so it loads the server.

Lost the pairing code

Run setup again (it prints the same code), or ask your agent to run whoami.

npx -y @irshad.io/figma-local-mcp@latest setup

"Not connected and no saved snapshot contains it"

The plugin isn't running and the node was never read before. Open the file in Figma Desktop, run the plugin and keep its window open.

use_figma can't edit the file

If you switched the file to Dev Mode, switch back to Design mode. Dev Mode is read-only, so edits only work in Design mode.

The plugin is refused

If whoami shows a refusedOrigin and you're sure it's the plugin, add that origin to FIGMA_LOCAL_MCP_ALLOW_ORIGINS.

Port 3947 is taken

Another instance of the server on the port is fine: requests go through it. If a different program holds port 3947, quit it. The plugin always connects to that port.

Still stuck?

Open an issue on GitHub with the output of whoami.