Skip to content
⌘K
How-To

Troubleshooting

The most common issues when setting up the Atelier workshop — symptom, cause, and a fix in three steps or less. Start with npm run preflight; it flags most of these automatically.

Storybook MCP server is unreachable

Symptom Claude Code says "storybook-angular" (or react/vue) is disconnected, or no component docs are returned.
Cause Your network blocks outbound HTTPS to atelier.pieper.io, or the server is temporarily down.
Fix
  1. Run `npm run preflight` — it pings each MCP endpoint and reports status codes.
  2. Test manually with `curl -I https://atelier.pieper.io/storybook-angular/mcp`. You should see a 200 or 405.
  3. If behind a corporate proxy, set `HTTPS_PROXY=http://your-proxy:port` before starting Claude Code.

Claude Code does not pick up the MCP config

Symptom The MCP servers are not listed in Claude Code, even though `.mcp.json` exists.
Cause Claude Code was started before `.mcp.json` existed, or the workspace is opened above the project root.
Fix
  1. Close and reopen the project in Claude Code from the directory containing `.mcp.json`.
  2. Check that `.mcp.json` is at the workspace root (not inside an app folder).
  3. Run `claude doctor` to verify MCP discovery.

Figma REST returns 403 / invalid token

Symptom REST-backed tools (file / variable / comment metadata reads) fail with "Forbidden" or "Invalid token". Interactive plugin tools still work.
Cause `FIGMA_ACCESS_TOKEN` is missing, expired, or does not have access to the target file. Only REST calls use it — the Desktop Bridge plugin does not.
Fix
  1. Verify the env var: `echo $FIGMA_ACCESS_TOKEN` (macOS/Linux) or `$env:FIGMA_ACCESS_TOKEN` (PowerShell).
  2. Confirm `.mcp.json` passes the token through — either inline or via `"FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"`. A bare shell export is not enough.
  3. Regenerate at https://www.figma.com/developers/api#access-tokens — scope: File content read.
  4. Make sure you are a member of the Figma team that owns the file, or use the public workshop demo file.

figma-console tools fail with "bridge not connected"

Symptom `figma_take_screenshot`, `figma_get_selection`, or `figma_execute` return "no active bridge" or time out. The MCP is loaded in Claude Code but has no Figma channel.
Cause The Desktop Bridge plugin is either not imported into Figma Desktop, not running, or cannot find the MCP on ports 9223–9232.
Fix
  1. Open Figma Desktop and run **Plugins → Development → Figma Desktop Bridge**. Leave the panel open while you work.
  2. If the plugin is missing from Development: re-run `npx -y figma-console-mcp@latest --help` to seed `~/.figma-console-mcp/plugin/`, then **Plugins → Development → Import plugin from manifest…** and pick that `manifest.json`.
  3. Restart Claude Code so the MCP re-claims a WebSocket port — the plugin scans 9223–9232 on open.

Every port 9223–9232 is already in use

Symptom figma-console MCP starts, but the Desktop Bridge panel stays on "searching…" indefinitely.
Cause The WebSocket port range 9223–9232 is fully occupied by unrelated processes, so the MCP cannot bind.
Fix
  1. Find the offender with `lsof -nP -iTCP:9223 -sTCP:LISTEN` (repeat for each port).
  2. Close unrelated processes, or restart your machine if the range is wedged.
  3. Windows: `netstat -ano | findstr 9223` then `taskkill /PID <pid> /F`.
Terminal window
# macOS / Linux — see who is on 9223
lsof -nP -iTCP:9223 -sTCP:LISTEN


# Free up 9223–9232 if safe
for p in 9223 9224 9225 9226 9227 9228 9229 9230 9231 9232; do
  lsof -ti :$p | xargs -r kill
done

Token Browser / Design System Dashboard missing

Symptom `ENABLE_MCP_APPS=true` is set, but the interactive MCP Apps UI (Token Browser, Design System Dashboard) never appears.
Cause Your MCP client does not implement the `ext-apps` protocol that those rich UIs require. Core tools still work.
Fix
  1. Use a client with `ext-apps` support (recent Claude Code builds qualify — run `claude --version` and upgrade if needed).
  2. Confirm the env var is actually reaching the child: add a `"LOG_LEVEL": "debug"` entry next to `ENABLE_MCP_APPS` and check the MCP startup line.
  3. If you only need the CLI tools (screenshots, selection, variable edits), you can safely drop `ENABLE_MCP_APPS`.

Node.js version too old

Symptom `npx create-atelier-ui-workspace` exits with `engines` or `Unsupported engine` errors.
Cause Atelier requires Node 22.12+ for Angular 21 and Astro 6 support.
Fix
  1. Install `nvm` (https://github.com/nvm-sh/nvm) — then `nvm install 22 && nvm use 22`.
  2. Verify with `node --version`. Must report v22.12.0 or newer.
  3. Re-run `npm run preflight` to confirm.

Permission denied running `npx create-atelier-ui-workspace`

Symptom `EACCES` errors during install, or "command not found" for a freshly installed global.
Cause npm is trying to write to a system-level directory that your user cannot access.
Fix
  1. Avoid `sudo npm install -g`. Instead, point npm at a user-owned prefix: see https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally.
  2. Or use nvm — it installs Node + npm into your home directory by default.
  3. On Windows, run the terminal as administrator for the first global install.

Port 4200 / 6006 already in use

Symptom `EADDRINUSE` when running `nx serve` or `storybook`.
Cause A previous dev server process is still running.
Fix
  1. macOS/Linux: `lsof -ti :4200 | xargs kill`.
  2. Windows: `netstat -ano | findstr :4200` → then `taskkill /PID <pid> /F`.
  3. Or run on a different port: `nx serve workshop-angular --port 4300`.

FIGMA_ACCESS_TOKEN vanishes after terminal restart

Symptom `echo $FIGMA_ACCESS_TOKEN` is empty in a new shell even though you set it yesterday.
Cause `export` only sets the variable for the current shell session — it does not persist. Also: Claude Code reads the env from `.mcp.json`, so even a persistent shell export has no effect unless `.mcp.json` references it via `${FIGMA_ACCESS_TOKEN}`.
Fix
  1. Add the export line to your shell rc file (see snippet below).
  2. In `.mcp.json`, make sure `"FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"` is under the `figma-console` env block — otherwise the shell value never reaches the MCP.
  3. Windows: use `[Environment]::SetEnvironmentVariable("FIGMA_ACCESS_TOKEN","figd_...","User")` once.
Terminal window
# macOS (zsh)
echo 'export FIGMA_ACCESS_TOKEN=figd_...' >> ~/.zshrc
source ~/.zshrc


# Linux (bash)
echo 'export FIGMA_ACCESS_TOKEN=figd_...' >> ~/.bashrc
source ~/.bashrc

Windows-specific path / symlink errors

Symptom `EPERM`, symlink failures, or mysterious path-too-long errors during `npm install`.
Cause Windows has stricter filesystem semantics than macOS/Linux — long paths and symlinks can fail.
Fix
  1. Enable long paths: `git config --system core.longpaths true` (admin PowerShell).
  2. Prefer WSL2 for Node.js work — run everything inside a WSL2 Ubuntu shell.
  3. If WSL is not an option, keep the workspace directory shallow (e.g. `C:\dev\my-workshop` instead of deeply nested).

Still stuck? Run npm run preflight and share its output — every line reports a specific fix.