ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Fix Website Screenshots Timing Out in an AI Agent

Find whether navigation, readiness, capture, or the agent deadline is timing out, then fix that specific stage with Playwright and MCP examples.

By the ScreenshotNeo team4 October 20268 min read

To fix website screenshots timing out in an AI agent, first identify which stage expired: navigation, a readiness wait, screenshot capture, image delivery or inspection, or the outer agent or service deadline. These stages have separate timeout controls in Playwright, and an AI agent may add its own deadline. Increasing the wrong timeout will not fix the failing stage.

The examples below use Playwright because the title does not specify an agent framework, browser host, or exact error. Treat the agent wrapper and hosted-browser limits as separate settings; Playwright’s timeout configuration does not establish or override them.

1. Identify the timeout boundary

Log the requested URL, each operation, elapsed time, and the exact error. Determine whether the failure happened in page.goto(), a readiness wait, page.screenshot(), image transfer or model processing, or the surrounding tool call. This diagnostic sequence follows from Playwright’s separate navigation and action timeout controls; there is no universal AI-agent log format.

const started = Date.now();
const mark = (stage) => console.log({ stage, elapsedMs: Date.now() - started });

try {
  mark('navigation-start');
  await page.goto('https://example.com', {
    waitUntil: 'domcontentloaded',
    timeout: 30_000,
  });
  mark('navigation-complete');

  await page.locator('main').waitFor({ state: 'visible', timeout: 10_000 });
  mark('readiness-complete');

  await page.screenshot({ path: 'page.png', timeout: 30_000 });
  mark('screenshot-complete');
} catch (error) {
  console.error({ stage: 'failed', elapsedMs: Date.now() - started, error });
  throw error;
}

Use a log or trace from the actual agent run if available. If Playwright has not reported its own timeout but the agent returns a timeout, check the orchestrator, MCP client and server, remote browser provider, and HTTP/request deadline. The error text and elapsed time help distinguish an inner browser timeout from an outer cancellation.

2. Make navigation wait for the right signal

Playwright’s page.goto() supports waitUntil values commit, domcontentloaded, load, and networkidle; its documented default is load. A page can keep analytics, polling, or streaming requests open after the content needed for a screenshot is visible, so network quiet may be the wrong readiness condition.

Condition Use when Trade-off
commit You need the navigation response to begin committing, then will wait for a specific page signal. Does not mean the DOM or visible content is ready.
domcontentloaded You need parsed HTML and can wait separately for the relevant content. Images, fonts, and other resources may still be loading.
load You need the page load event and it is appropriate for the site. This is Playwright’s default and can wait on slow resources.
networkidle A particular workflow truly requires network quiet and the site can reach it. Ongoing requests can prevent it. Playwright labels this condition discouraged for testing.

Prefer a task-specific selector or state when you can identify one. Playwright’s API documentation says not to use networkidle for testing and recommends assertions to assess readiness instead. This is guidance for Playwright; other browser tools may define readiness differently.

await page.goto('https://example.com', {
  waitUntil: 'domcontentloaded',
  timeout: 30_000,
});
await page.locator('main article').waitFor({ state: 'visible', timeout: 10_000 });

Choose the selector for the content the task actually needs. A generic element such as body may appear before a client-rendered page has populated its main content.

3. Configure the timeout for the failing operation

Playwright has separate navigation and general operation timeout controls. Navigation methods use the navigation timeout when set; otherwise they use the general default. Screenshot options also have a timeout, and defaults can be set at page or browser-context level. Confirm the effective value for the specific call before changing it.

// Configure defaults for this page.
page.setDefaultTimeout(15_000);
page.setDefaultNavigationTimeout(45_000);

// Or set a timeout on the individual navigation and capture calls.
await page.goto('https://example.com', {
  waitUntil: 'domcontentloaded',
  timeout: 45_000,
});
await page.screenshot({ path: 'page.png', timeout: 30_000 });

Set a larger capture timeout only when logs show that screenshot capture itself is expiring and the enclosing agent deadline leaves enough time. A timeout increase cannot help if the agent or service cancels the whole call first. No universal timeout duration is recommended by the cited Playwright API for AI-agent screenshots.

4. Reduce screenshot work when the task allows it

Playwright can capture the current viewport or a full scrollable page. A full-page image can require more work and produce more data; when the task only needs what is visible, start with a viewport capture. If one component is all that matters, capture its locator. These are useful diagnostics, not guaranteed fixes for every timeout.

// Viewport only
await page.screenshot({ path: 'viewport.png', fullPage: false, timeout: 30_000 });

// A specific element
await page.locator('main article').screenshot({ path: 'article.png', timeout: 30_000 });

// Full page, only when content below the fold is needed
await page.screenshot({ path: 'full-page.png', fullPage: true, timeout: 45_000 });

For Playwright MCP, the screenshot tool can capture the viewport, a target element, or the full page. Its guide says that fullPage cannot be combined with an element target. Use the viewport/element/full-page option supported by the MCP tool version you have installed.

5. Separate screenshot capture from image inspection and interaction

A screenshot may have completed successfully even if the agent appears to hang afterward. Check whether the delay is in transferring a large image, returning it through MCP, model-side visual processing, or the next browser action. For Playwright MCP specifically, screenshots are for visual observation; use browser_snapshot references for interaction. Other agent tools may use different interaction semantics.

Record a timestamp when the browser tool returns and another when the agent finishes processing the result. If the browser returns within its configured timeout but the whole task expires later, investigate the outer tool-call deadline or image-processing stage instead of raising the browser timeout.

6. Avoid fixed sleeps as a production remedy

A fixed delay waits the same amount whether the page is ready immediately or still not ready when the delay ends. Playwright marks waitForTimeout() as discouraged and says never to wait for a timeout in production; its API documentation notes that timer-based tests are inherently flaky. Use a selector or meaningful page state instead.

// Avoid using a fixed sleep to guess when content is ready:
// await page.waitForTimeout(5000);

// Wait for the actual content the screenshot needs:
await page.locator('[data-report-ready="true"]').waitFor({
  state: 'visible',
  timeout: 15_000,
});

7. Troubleshoot common timeout symptoms

Symptom Likely cause What to do
page.goto() times out The selected load condition is too strict for the site, a resource is slow, or navigation is blocked. Check the failing URL and navigation logs. Try an earlier appropriate condition such as domcontentloaded, then wait for the task’s actual content. Raise the navigation timeout only if the navigation itself legitimately needs more time.
waitForLoadState('networkidle') never completes Ongoing requests keep the page from becoming idle. Use a task-specific selector or state if possible. Playwright discourages networkidle for tests.
The page loaded but screenshot() times out The capture operation has its own effective timeout, or the capture scope is unnecessarily large. Check the screenshot timeout. Try viewport or element capture if that satisfies the task; use full-page only when needed.
The agent reports timeout after the browser call returns Image transfer/inspection or the outer tool, orchestration, MCP, provider, or request deadline may be expiring. Compare browser-return and agent-completion timestamps; inspect the relevant wrapper’s deadline and logs.
A fixed sleep sometimes works, sometimes fails Page readiness varies and the delay is only a guess. Wait for the relevant selector or state with a bounded timeout.
An element screenshot fails with full-page enabled In Playwright MCP, full-page and element target modes cannot be combined. Choose one mode: capture the element or capture the full page.

8. Performance, reliability, and cost considerations

  • Performance: Capture only the pixels the task needs. Viewport or element images can reduce capture and image-transfer work compared with a full-page image, but the actual time depends on the page and runtime.
  • Reliability: Use bounded operation timeouts and a readiness signal tied to the requested content. Keep the outer deadline longer than the operations it contains, with room for result transfer and agent processing.
  • Retries: Retry only after classifying the failure. A repeated navigation timeout, blocked page, or permanently busy network is unlikely to be solved by blindly repeating the same full-page capture. This is operational guidance, not a Playwright guarantee.
  • Cost: Playwright’s cited API guidance does not set a universal cost or timeout price. For a hosted browser or agent, check its own billing and request limits; do not assume that changing Playwright settings changes provider charges.

9. Use Playwright MCP with the right capture mode

If the AI agent uses Playwright MCP, configure and inspect the MCP tool call separately from the browser operations it invokes. Use the MCP guide for the tool’s accepted arguments, choose viewport, element, or full-page capture based on the task, and use snapshot references when the agent needs to interact with the page. An MCP client’s own deadline may still be shorter than the browser call’s timeout.

Or skip the browser setup

For a one-call website screenshot API, use ScreenshotNeo. See the ScreenshotNeo API documentation for request options and response behavior.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);
  • Cookie banners are accepted and removed before the shot; 60+ known consent platforms, newsletter popups, and chat widgets are handled, and each step can be turned off.
  • Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
  • An MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
  • 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

Frequently asked questions

Does a screenshot timeout mean the website blocked the AI agent?

Not by itself. A timeout identifies an operation that exceeded a deadline; inspect the failing stage and error before concluding whether the site, browser, or outer tool caused it.

Should I always use domcontentloaded?

No. Choose the earliest navigation condition that fits the task, then wait for the specific content required. Some tasks need additional page state or resources.

Does increasing the Playwright timeout fix an MCP timeout?

Only if the browser operation is the part expiring and the MCP client/server deadline allows it to continue. The MCP and orchestration limits must be checked independently.

Can I take a full-page screenshot of an element in Playwright MCP?

No. The Playwright MCP guide says full-page mode cannot be combined with an element target; choose the capture mode that matches the required image.

Sources

  • Playwright Page API — navigation and operation timeouts, load-state guidance, screenshot options, and fixed-wait guidance.
  • Playwright MCP tools — screenshot capture modes and browser snapshot interaction guidance.

Keep reading