Timeout Issues

This document explains the different types of timeouts you may encounter when using Browserless and how to resolve them. Understanding and properly configuring timeouts is crucial for reliable browser automation.

Types of Timeouts

There are several types of timeouts in browser automation:

• Browser Session Timeouts: Maximum duration a browser session can run
• Reconnection Timeouts: Maximum duration a browser session is kept alive while waiting to be reconnected to.
• Session State TTL: Maximum time a sessions state is persisted.
• Action Timeouts: Time to wait for user actions like navigating, waiting for a selector, clicks, typing, etc. to complete

Browser Session Timeouts

Browser session timeouts control the maximum duration a browser session can run. You can override the default session timeout using the timeout parameter in your connection URL: If you need a longer timeout, you can view our pricing page to choose the best plan for your needs.

JavaScript

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&timeout=300000`,
});
//The timeout value is specified in milliseconds (300000ms = 5 minutes).

Python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        "wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE&timeout=300000"
    )
    # The timeout value is specified in milliseconds (300000ms = 5 minutes).

Reconnection Timeouts

When using Standard Sessions, you may generate a browserWSEndpoint that you can reconnect to in the future. Browsers stay alive when you use the Browserless.reconnect CDP command, and if they aren't reconnected to on time, they will timeout and close. You can read more about our Reconnection timeout here.

Session State TTL

Session State TTL (Time to Live) is set when a session is created through the /session API and it determines how long session state data like cookies, local storage, and session data is persisted. This affects how long your browser session can maintain its state between connections. You can read more about Persisting States here.

Action Timeouts

Most puppeteer or playwright actions have individual timeout values, which control how long individual actions can take, including navigation, waiting for selectors, clicks, typing, and other user interactions.

Navigation Timeouts

Navigation timeouts occur when page.goto() takes too long to complete.

JavaScript

await page.goto('https://example.com', {
  timeout: 60000, //This is the navigation timeout
  waitUntil: 'networkidle2'
});

Python

page.goto('https://example.com', 
  timeout=60000,  # This is the navigation timeout
  wait_until='networkidle'
)

Understanding waitUntil Options

The waitUntil option determines when navigation is considered complete. Different options can significantly impact loading times:

• load: Wait for the load event
• domcontentloaded: Wait for DOMContentLoaded event
• networkidle0: Wait until there are no network connections for 500ms
• networkidle2: Wait until there are no more than 2 network connections for 500ms

For detailed guidance on choosing the right waitUntil option, see our waitUntil blog post.

Selector Timeouts

Selector timeouts occur when waiting for elements to appear on the page. The default timeout is typically 30 seconds.

JavaScript

await page.waitForSelector('#my-element', {
  timeout: 60000,
  visible: true
});

Python

    page.wait_for_selector('#my-element', 
        timeout=60000,
        state='visible'
    )

User Action Timeouts

Action timeouts can occur when elements are not immediately clickable, when typing into fields, or when the page is still loading during user interactions.

JavaScript

await page.click('#my-button', {
  timeout: 30000
});
await page.type('#my-input', 'Hello World', {
  timeout: 30000
});

Python

page.click('#my-button', timeout=30000)
page.fill('#my-input', 'Hello World', timeout=30000)

Getting Help

If you continue to experience timeout issues after following this guide:

1. Check your plan's timeout limits in the pricing page
2. Contact Browserless support for assistance

For free plan users experiencing frequent timeouts, we recommend upgrading to a paid plan for longer session durations and better performance.