Playwright MCP Server Not Working? 12 Common Errors and How to Fix Them (2026)

You followed the setup guide, added the Playwright MCP Server to Claude, typed your first prompt… and nothing happened. Or the server shows failed. Or the browser opens once and never again. Playwright MCP is powerful, but its errors are often vague, and the fix usually depends on your OS, your MCP client, and how the browser was launched.

This guide collects the 12 most common Playwright MCP Server errors we see when setting it up with Claude Code, Claude Desktop, Cursor, and VS Code, grouped by where they happen. For each one: what it looks like, why it happens, and the exact fix.

Startup & Connection Errors

1. spawn npx ENOENT / server fails to start

What you see: the MCP client reports that the server failed to start, and the logs mention spawn npx ENOENT or "command not found".

Why: the MCP client cannot find npx. This is very common in Claude Desktop and on Windows, because GUI apps do not always inherit the PATH from your terminal — especially if Node was installed with nvm.

Fix: use the full path to npx, or on Windows wrap it with cmd /c:

# macOS / Linux
which npx      # e.g. /Users/you/.nvm/versions/node/v22.11.0/bin/npx

# Windows (PowerShell)
where.exe npx

{
  "mcpServers": {
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "@playwright/mcp@latest"]
    }
  }
}

2. Old Node.js version

What you see: syntax errors on startup, or errors about unsupported features, immediately after npx downloads the package.

Why: Playwright MCP needs a modern Node.js (18 or newer; use the current LTS). The Node your MCP client picks up may be older than the one in your terminal.

Fix: run node -v, upgrade to the current LTS, and if you use nvm, point the config at that version's full npx path (see error #1).

3. Server times out on first launch

What you see: the server shows as failed the very first time, then works on the second try.

Why: the first npx @playwright/mcp@latest run downloads the package. On a slow connection this takes longer than the client's startup timeout.

Fix: pre-install once from a terminal so later starts are instant, and in Claude Code raise the startup timeout with the MCP_TIMEOUT environment variable:

# Warm the npx cache
npx @playwright/mcp@latest --help

# Give MCP servers 30s to start (Claude Code)
MCP_TIMEOUT=30000 claude

4. Server is configured, but Claude doesn't see the tools

What you see: you added the server, but Claude says it has no browser tools, or claude mcp list doesn't show playwright in this project.

Why: MCP servers in Claude Code have a scope. A server added with the default (local) scope only exists in the directory where you added it. A server in a project's .mcp.json must be approved the first time.

Fix: add it at user scope if you want it everywhere, then restart the session:

claude mcp add playwright -s user -- npx @playwright/mcp@latest
claude mcp list

For Claude Desktop and Cursor, the equivalent fix is simply fully quitting and reopening the app after editing the config file — config changes are only read at startup. Also double-check the JSON is valid; a single trailing comma silently disables every server in the file.

Browser Launch Errors

5. "Browser is already in use"

What you see: an error like "Browser is already in use for …/mcp-chrome-profile, use --isolated to run multiple instances of the same browser".

Why: by default Playwright MCP uses a persistent browser profile. Only one browser can use a profile at a time. A second Claude session, a second MCP client, or a leftover browser process from a crashed session is holding the lock.

Fix: close the other session (or the orphaned Chrome window), or run each session with its own clean profile:

claude mcp add playwright -- npx @playwright/mcp@latest --isolated

Isolated mode starts a fresh, in-memory profile every time. If you still need to be logged in, pair it with a storage state file — see Playwright MCP Authentication.

6. Chrome not found / browser executable doesn't exist

What you see: errors saying the chrome distribution is not found, or that an executable doesn't exist and you should run npx playwright install.

Why: Playwright MCP launches Google Chrome by default. On machines without Chrome (many Linux boxes, Docker images, fresh VMs) there is nothing to launch.

Fix: install Chrome through Playwright, or tell the server to use a different browser:

# Install Google Chrome via Playwright
npx playwright install chrome

# ...or run with another browser
npx @playwright/mcp@latest --browser firefox

7. "Missing X server or $DISPLAY" on Linux, WSL, or Docker

What you see: the browser fails to launch with a message about a missing X server or display.

Why: the server is trying to open a headed (visible) browser on a machine with no screen — a remote Linux server, WSL without a GUI, a container, or CI.

Fix: run headless:

npx @playwright/mcp@latest --headless

8. Missing system libraries on Linux

What you see: the browser crashes on launch with errors about missing shared libraries (.so files).

Fix: install the OS dependencies Playwright's browsers need. On Docker, start from the official Playwright image instead — see the Playwright Docker tutorial.

sudo npx playwright install-deps

Runtime & Agent Errors

9. "Ref not found" — the agent clicks an element that no longer exists

What you see: a tool call fails with a message that an element ref (like e42) was not found in the current snapshot, and suggests capturing a new one.

Why: Playwright MCP gives the agent element references from an accessibility snapshot of the page. If the page navigated, re-rendered, or a modal opened after that snapshot, the old refs are stale.

Fix: usually the agent recovers on its own by taking a new snapshot. If it keeps looping, add this to your prompt or CLAUDE.md: "After every navigation or click that changes the page, take a fresh snapshot before the next action." Apps with clear accessible names also produce far more stable snapshots — see ARIA snapshot testing.

10. Context fills up and the agent gets slow or "forgets"

What you see: long sessions get slower, the agent repeats steps, or you hit context limits on large pages.

Why: every snapshot of a big page (dashboards, long tables, marketing pages) is sent to the model. Twenty actions on a heavy page adds up to a lot of tokens.

Fix: keep sessions focused on one flow, start a new session per feature, and ask the agent to work on specific regions rather than whole pages. For repeatable runs, convert what the agent learned into a normal Playwright test instead of re-exploring every time. We measured the trade-offs in Playwright CLI vs MCP Server token cost.

11. The agent keeps landing on the login page

What you see: every session starts logged out, the agent types credentials every time, or you get rate-limited or "new sign-in" alerts.

Fix: save a session once and load it with --isolated --storage-state=playwright/.auth/user.json. Never paste passwords into prompts. The full setup, including MFA handling, is in Playwright MCP Authentication.

12. Pages won't load behind a corporate proxy or VPN

What you see: navigation times out or fails for internal or external sites, but the same URL works in your normal browser.

Why: the browser launched by MCP doesn't automatically use your company's proxy settings.

Fix: pass the proxy explicitly:

npx @playwright/mcp@latest --proxy-server=http://proxy.company.com:8080

Quick Reference: Symptom → Fix

Frequently Asked Questions

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn