Skip to main content
Version: v2

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:

  • Session Timeouts: Maximum duration a browser session can run
  • Navigation Timeouts: Time to wait for page navigation to complete
  • Selector Timeouts: Time to wait for elements to appear on the page
  • Action Timeouts: Time to wait for user actions like clicks, typing, etc. to complete

Global Session Timeouts by Plan​

Browserless enforces global session timeouts based on your subscription plan:

PlanMax Session TimeConcurrent Browsers
Free60 seconds1
Prototyping15 minutes3
Starter30 minutes20
Scale60 minutes50
EnterpriseCustomCustom

Upgrading for Longer Sessions​

If you're on the Free plan and experiencing session timeouts, consider upgrading to a higher-tier plan:

  • Prototyping plan provides 15-minute sessions
  • Starter plan provides 30-minute sessions
  • Scale plan provides 60-minute sessions
  • Enterprise plan provides unlimited session duration

View pricing details to choose the best plan for your needs.

Overriding Session Timeouts​

You can override the default session timeout using the timeout parameter in your connection URL:

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).

Navigation timeouts occur when page.goto() takes too long to complete. The default timeout is typically 30 seconds.

Increasing Navigation Timeouts​

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE`,
});

const page = await browser.newPage();

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

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.

Increasing Selector Timeouts​

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE`,
});

const page = await browser.newPage();
await page.goto('https://example.com');

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

Setting Default Timeouts​

You can set default timeouts for all operations on a page:

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE`,
});

const page = await browser.newPage();
page.setDefaultTimeout(60000);
page.setDefaultNavigationTimeout(90000);

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.

Increasing Action Timeouts​

import puppeteer from "puppeteer-core";

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://production-sfo.browserless.io/?token=YOUR_API_TOKEN_HERE`,
});

const page = await browser.newPage();
await page.goto('https://example.com');

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

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

Best Practices​

  1. Set Realistic Timeouts: Don't set timeouts too low for slow-loading pages, but don't set them unnecessarily high either.

  2. Use Appropriate waitUntil Options: Choose the right waitUntil option based on your needs. See our waitUntil guide for details.

  3. Handle Timeouts Gracefully: Always wrap timeout-prone operations in try-catch blocks.

  4. Monitor Session Duration: Keep track of how long your sessions run to avoid hitting plan limits.

  5. Close Browsers Properly: Always close browser instances to prevent hitting concurrency limits.

Troubleshooting Common Issues​

"TimeoutError: Navigation timeout exceeded"​

This error occurs when page.goto() takes longer than the specified timeout.

Solutions:

  • Increase the navigation timeout
  • Use a more appropriate waitUntil option
  • Check if the target website is responding slowly
  • You might be experiencing bot detection - see our anti-bot detection documentation for solutions like using proxies, setting headless=false, or using BrowserQL for advanced stealth techniques

"TimeoutError: Waiting for selector timed out"​

This error occurs when an element doesn't appear within the specified time.

Solutions:

  • Increase the selector timeout
  • Verify the selector is correct
  • Check if the element appears after user interaction
  • Use waitForFunction for complex conditions

"Session terminated due to timeout"​

This error occurs when your session exceeds the plan's maximum duration.

Solutions:

  • Optimize your automation to run faster
  • Break long operations into smaller sessions
  • Upgrade to a plan with longer session limits

Getting Help​

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

  1. Check your plan's timeout limits in your account dashboard
  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.