How to Fix Playwright MCP Screenshot Timeouts on Slow Websites

Start by identifying which operation timed out. Playwright MCP has separate limits for actions, navigation, and the short wait after an action for triggered work to settle. Raising the wrong one may not help. Even when navigation completes, wait for the page content your image needs before capturing it.

The documented defaults are 5,000 ms for actions, 60,000 ms for navigation, and 500 ms for post-action settle. The server can set these with command-line flags or environment variables; confirm the defaults for the version you run. [Playwright MCP configuration](https://github.com/microsoft/playwright-mcp#configuration)

1. Identify what is still waiting

Read the exact tool error and inspect the call immediately before it. A timeout may come from navigation, an action such as a click, MCP’s post-action settle period, an explicit wait, or the MCP host’s own request deadline. These are different stages, and the three MCP timeout settings do not necessarily control all of them.

What appears stuck	Setting to inspect first
Opening a URL or waiting for a navigation event	Navigation timeout
Clicking or performing another browser action	Action timeout; also check whether the action triggers navigation
Tool response pauses after an action completes	Settle timeout and ongoing triggered work
Screenshot returns, but the page is blank or incomplete	Content readiness; wait for a relevant signal before capture
Everything waits longer than the server setting permits	MCP client or host request deadline, if applicable

The screenshot reference does not document a separate configurable screenshot-timeout option. Don’t assume that increasing the navigation limit will fix a client deadline or a content-readiness problem. [Playwright MCP screenshot reference](https://github.com/microsoft/playwright-mcp#browser-screenshot)

2. Set the timeout for the operation that is slow

Playwright MCP documents these flags and equivalent environment variables:

Purpose	Flag	Environment variable	Documented default
Browser actions	--timeout-action	PLAYWRIGHT_MCP_TIMEOUT_ACTION	5,000 ms
Navigation	--timeout-navigation	PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION	60,000 ms
Post-action settle	--timeout-settle	PLAYWRIGHT_MCP_TIMEOUT_SETTLE	500 ms

For example, if a legitimate navigation takes longer than the documented default, launch the server with a larger navigation limit:

npx @playwright/mcp@latest --timeout-navigation 90000

Or configure the same value through the server process environment:

PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION=90000 npx @playwright/mcp@latest

These examples show server launch configuration. The exact place to set it depends on how your MCP host starts the server; the host may not expose every launch option. After changing the launch configuration, restart or reconnect the server as required by that host, then confirm which server version and effective configuration are in use. The documented values are defaults, not a promise that any site will load within them.

Increase the action limit only when the action itself is the slow stage. Adjust settle only when the action finishes but MCP waits too long for triggered work. A longer settle interval can make every action feel slower; it is not a substitute for a page-specific readiness check. [Playwright MCP configuration](https://github.com/microsoft/playwright-mcp#configuration)

3. Choose a navigation wait condition, then wait for useful content

Playwright supports four navigation lifecycle conditions: commit, domcontentloaded, load, and networkidle. They describe different stages. commit means the response arrived and document loading began; domcontentloaded waits for the DOM content event; load waits for the load event. networkidle waits for at least 500 ms without network connections.

Don’t treat networkidle as the default fix. Pages with polling, analytics, streaming, or other ongoing requests may not become idle, and network quiet does not prove that the exact image or text you need has rendered. Playwright discourages using networkidle for tests and recommends assertions about readiness instead. [Playwright navigation API](https://playwright.dev/docs/api/class-page#page-wait-for-load-state)

A practical approach is to use the earliest lifecycle event suitable for starting work, then explicitly wait for a meaningful page signal. That recommendation follows from the documented lifecycle meanings and readiness guidance; the right signal depends on the site and the screenshot.

In an MCP session, use browser_wait_for to wait for relevant text to appear or disappear. When text matching is insufficient, the MCP waiting guide describes selector waits and custom conditions, including a JavaScript predicate or a specific response through browser_run_code_unsafe. Choose a signal that indicates the content in the image is ready, such as the report heading or a results-loaded label. [Playwright MCP waiting guide](https://github.com/microsoft/playwright-mcp#waiting-for-the-page)

For example, the sequence in your MCP client should be conceptually:

browser_navigate({ url: "https://example.com/report" })
browser_wait_for({ text: "Quarterly report" })
browser_take_screenshot({ fullPage: false })

The tool names and arguments shown here illustrate the sequence; follow the schema exposed by your installed MCP server version. If the needed condition is a CSS selector or response rather than visible text, use the corresponding supported wait mechanism.

A fixed sleep is not a reliable production readiness condition. Playwright says page.waitForTimeout() should be used only for debugging, not production, because fixed waits are flaky; prefer locator actions and assertions that wait for a condition. [Playwright page API: waitForTimeout](https://playwright.dev/docs/api/class-page#page-wait-for-timeout)

4. Capture only the scope you need

Playwright MCP screenshots capture the current viewport by default. Use target to capture a particular element, or fullPage: true to capture the full scrollable page. Full-page capture cannot be combined with target.

// Current viewport
browser_take_screenshot({})

// A single element
browser_take_screenshot({ target: "main article" })

// The full scrollable page
browser_take_screenshot({ fullPage: true })

Use the actual screenshot tool and parameter names exposed by your server version. A full-page image may take more work and produce a larger result than a viewport or element capture, so choose it only when the entire page is part of the deliverable. If you need page text or structure rather than visual appearance, request an accessibility snapshot instead. [Playwright MCP screenshot reference](https://github.com/microsoft/playwright-mcp#browser-screenshot) · [Playwright MCP snapshots](https://github.com/microsoft/playwright-mcp#browser-snapshot)

5. Troubleshoot by symptom

Symptom	Likely cause	What to do
Navigation never reaches the expected URL or document event	The site is slow, the chosen lifecycle event takes too long, or navigation is failing	Check the exact navigation error and effective navigation timeout. Raise that limit only if the navigation is legitimately slow. Consider an earlier lifecycle condition followed by a content-specific wait.
A click or other action exceeds its limit	The action is slow, blocked, or waiting on a navigation it triggered	Inspect the action timeout separately from navigation. Check whether the action should cause navigation and whether the page reaches the expected destination.
The tool pauses after an action	MCP is waiting for triggered requests or navigation to settle	Inspect the settle setting and identify relevant page readiness directly instead of waiting on unrelated background activity.
Screenshot is blank, partial, or still loading	The capture ran before the required content was ready	Wait for a relevant text, selector, predicate, or response, then capture the viewport, target element, or full page as appropriate.
Full-page capture is slow or too large	The task may not need the entire scrollable page	Use a viewport screenshot or target an element if that includes everything you need.
Increasing a server timeout has no effect	The wrong stage is timing out, the server did not restart with the change, or the client has a separate deadline	Confirm the server version, startup options, failing tool call, and exact error. Check the MCP host’s request deadline if it cuts off the call first.
Page remains blocked or loads indefinitely	The site may be failing, blocked, or continuing work without completing	Inspect browser and network behavior and determine whether the page can reach the content condition. A larger timeout cannot guarantee that a blocked or failed page will recover.

6. Collect these details for a precise diagnosis

• Playwright MCP server version and MCP host/client.
• Exact error text and the tool call that failed.
• Effective startup flags or environment variables.
• Whether the failure happens during navigation, action, settle, explicit wait, or capture.
• Whether the requested image is a viewport, target element, or full page.
• Which page-specific signal indicates the desired content is ready.

If the matching timeout and a targeted readiness condition do not resolve the issue, inspect browser logs and network behavior. A client-side request deadline may be separate from the server settings; the documentation does not establish one universal client deadline or a definitive remedy for blocked or indefinitely loading sites.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. Its [API documentation](https://screenshotneo.com/docs/) covers the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners are accepted like a visitor and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before the shot; each step can be turned off.
• Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers report the page verdict and billing status.
• An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
• 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, with no card required.

FAQ

Which Playwright MCP timeout should I increase?

Increase the navigation limit for slow navigation, the action limit for a slow action, or review settle when MCP pauses after an action. First confirm which stage actually timed out.

How do I wait for a slow page before taking a screenshot?

Wait for a page-specific text, selector, predicate, or response that signals the required content is ready, then capture. MCP provides browser_wait_for for explicit waiting.

Should I use networkidle?

Usually not as a default. Ongoing requests can prevent it, and network quiet does not establish that the content you need is ready. Prefer a condition tied to that content.

Can I capture a specific element and the full page together?

No. MCP’s screenshot reference says target and fullPage: true cannot be combined.

Why does a screenshot tool have no separate timeout setting?

The consulted MCP screenshot reference defines capture modes but does not document a separately configurable screenshot timeout. Diagnose the operation that is waiting and check for a host-side deadline.