Troubleshooting

Fixes for the most common errors when running Framelink MCP for Figma. If your problem isn’t listed here, ask in our Discord server or open an issue on GitHub.

Find your error

Match what you see to the section that fixes it.

What you see	Go to
`fetch failed`, `ECONNRESET`, or `Connection was reset`	Network proxy and connection errors
`Cannot find module 'xxxxx'`	Cannot find module
403 Forbidden with `"err":"Invalid scope(s): ..."`	Invalid scope(s)
403 Forbidden with `"err":"Invalid token"`	Invalid token
403 Forbidden with `"err":"Token expired"`	Token expired
403 Forbidden with `"err":"File not exportable"`	File not exportable
403 Forbidden with any other body, or an HTML page	Other causes
`429`, `Too Many Requests`, or `Figma API rate limit hit`	429 Too Many Requests
Claude Desktop runs the server with the wrong Node.js version	Claude Desktop: wrong Node version

Network proxy and connection errors

If you see errors like fetch failed, ECONNRESET, or Connection was reset, your network likely requires outbound traffic to go through a proxy server. This is common on corporate networks, university campuses, and other managed environments.

Add the `--proxy` flag

Ask your IT department for your proxy URL, then add --proxy to your MCP server configuration:

MCP client configuration

{
  "mcpServers": {
    "Framelink_Figma_MCP": {
      "command": "npx",
      "args": [
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR-KEY",
        "--proxy=http://your-proxy:8080",
        "--stdio"
      ]
    }
  }
}

Alternatively, you can set the FIGMA_PROXY environment variable instead.

Standard proxy environment variables

The server also automatically respects the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. If your system already has these set and your MCP client propagates them to child processes, proxy support should work without any additional configuration.

Bypassing a misbehaving proxy

If you have a proxy set in your environment (from a VPN client, old dev tooling, or inherited shell config) that is rejecting requests to api.figma.com specifically, you have two options:

Add api.figma.com to the NO_PROXY environment variable: NO_PROXY=api.figma.com. This is the standard convention and also respected by curl, git, npm, and most other tools.
Pass --proxy=none to the server (in place of the --proxy=... line in the config above). This ignores HTTP_PROXY/HTTPS_PROXY entirely and connects directly. Useful when modifying environment variables is awkward — e.g. the proxy is set at the system level or inherited from a parent process.

Cannot find module

If you encounter an error like Cannot find module 'xxxxx', it means that something went wrong with installation of the MCP server. To fix this, close your client and try running the following command:

npx clear-npx-cache

Then open your client again. If the issue persists, please join our Discord server or leave an issue on Github and we’ll help you out.

403 Forbidden when accessing Figma files

A 403 from the Figma API can have several distinct causes, and each has a different fix. Figma names the cause in the "err" field of the response body. The server includes that body verbatim in its error message (as Response body: ...), so find the err string in the error your MCP client surfaced and match it to a section below.

Example response body

{"status":403,"err":"Invalid scope(s): ..."}

`"Invalid scope(s): ..."`

Your Personal Access Token was created without the scopes this MCP needs to read file content. Figma tokens are scoped, and tokens generated through the current UI do not always include the scopes we require by default. Fix: Generate a new PAT at Figma Settings → Security → Personal access tokens (navigation instructions) with at least these scopes selected, then update your MCP configuration:

file_content:read
file_dev_resources:read

The quickstart lists the full set of scopes to enable, including the ones newer MCP features need. Granting all of them now saves you regenerating the token later.

`"Invalid token"`

Figma did not recognize the token being sent. Common causes:

The token was revoked or deleted from your Figma settings
The token was mistyped, truncated, or picked up stray whitespace when copied into your MCP config
The value being sent isn’t actually a Figma token (e.g. a placeholder was left in place)

Fix: Generate a fresh PAT at Figma Settings → Security → Personal access tokens (navigation instructions) with the scopes listed above and update your MCP configuration.

`"Token expired"`

OAuth access tokens have a limited lifetime. Once expired, every request returns 403 until you obtain a new one. Fix: Refresh your OAuth access token through your OAuth flow. If OAuth isn’t essential for your setup, switching to a Personal Access Token avoids the refresh step — a PAT lasts until the expiration you chose when creating it.

`"File not exportable"`

The file’s share settings disallow copying, sharing, and exporting. The Figma API honors these settings. Fix: If you own the file, open it in Figma, click Share, and allow viewers to copy, share, and export. If you don’t own it, ask the owner to update the setting or duplicate the file into your own workspace.

Figma share dialog with the option allowing viewers to copy, share, and export

Other causes

If the error body doesn’t match one of the above:

File access — The file must be owned by the account associated with your token, or explicitly shared with that account. For team/org files, the token’s account must belong to the right team.
HTTP proxy or firewall — A proxy or intermediary can return its own 403 before the request reaches Figma. If the response body doesn’t look like Figma’s usual JSON (e.g. HTML, a third-party vendor name, “Access denied” text), an intermediary is likely the cause. See the network proxy section for how to bypass a misbehaving proxy.

429 Too Many Requests

If you encounter a 429: Too Many Requests error, it means you have exceeded the Figma API rate limits. There is no rate limiting built into Framelink MCP for Figma itself; these limits come directly from Figma. The server’s error message passes along what Figma reports: how many seconds to wait before retrying, whether your seat type (Viewer or Collaborator) has a lower limit, whether the plan is Starter or Student, and an upgrade link when Figma provides one. There are a few common causes and solutions for this issue.

Upgrade to a Paid Plan

Your rate limits depend on your Figma plan:

Free Plan: Limited to approximately 6 requests per month.
Any Paid Plan (including Dev Seats): Starts at 10 requests per minute for the endpoints used by Framelink.

For more details, see Figma’s Rate Limit documentation.

Check File Ownership

Rate limits are determined by the file owner’s plan in addition to your account’s plan.

If you are accessing a file in a Starter plan team/project, you will be subject to Starter limits (very low).
Solution: Duplicate the file into your own paid workspace/team. Your paid plan limits will then apply to the copy.

Wait for API Limits to Update

If you recently upgraded to a paid plan, there might be a delay before the API limits are updated. Some users report this can take some time to propagate.

Claude Desktop: wrong Node version

If you use a version manager like NVM to manage your Node.js version, you may run into an issue where Claude Desktop ends up using the wrong version of Node.js. To fix this, you can create a special version of npx for Claude Desktop to use that uses the right version of Node.js.

/usr/local/bin/npx-for-claude

#!/bin/zsh

# You may need to update this path to match your shell. This line is meant
# to load the file that sets the path to the Node.js version you want.
source ~/.zshrc
exec npx "$@"

Then run chmod +x /usr/local/bin/npx-for-claude to make it executable. Update your configuration in Claude Desktop to use this new npx command instead of the default one.

Claude Desktop configuration

{
  "mcpServers": {
    "Framelink_Figma_MCP": {
      "command": "npx-for-claude",
      "args": [
        "-y",
        "figma-developer-mcp",
        "--figma-api-key=YOUR-KEY",
        "--stdio"
      ]
    }
  }
}

Get started

Guides

Reference

Find your error

Network proxy and connection errors

Add the `--proxy` flag

Standard proxy environment variables

Bypassing a misbehaving proxy

Cannot find module

403 Forbidden when accessing Figma files

`"Invalid scope(s): ..."`

`"Invalid token"`

`"Token expired"`

`"File not exportable"`

Other causes

429 Too Many Requests

Upgrade to a Paid Plan

Check File Ownership

Wait for API Limits to Update

Claude Desktop: wrong Node version

​Find your error

​Network proxy and connection errors

​Add the --proxy flag

​Standard proxy environment variables

​Bypassing a misbehaving proxy

​Cannot find module

​403 Forbidden when accessing Figma files

​"Invalid scope(s): ..."

​"Invalid token"

​"Token expired"

​"File not exportable"

​Other causes

​429 Too Many Requests

​Upgrade to a Paid Plan

​Check File Ownership

​Wait for API Limits to Update

​Claude Desktop: wrong Node version

Find your error

Network proxy and connection errors

Add the `--proxy` flag

Standard proxy environment variables

Bypassing a misbehaving proxy

Cannot find module

403 Forbidden when accessing Figma files

`"Invalid scope(s): ..."`

`"Invalid token"`

`"Token expired"`

`"File not exportable"`

Other causes

429 Too Many Requests

Upgrade to a Paid Plan

Check File Ownership

Wait for API Limits to Update

Claude Desktop: wrong Node version