MegalaniaBlog
  1. Blog
  2. How to fix
  3. Puppeteer timeout

Puppeteer timeout: navigation and selector timeouts, fixed

Puppeteer stops after 30 seconds by default. What a hung server and a missing selector look like, how to catch TimeoutError, and the fix. Puppeteer 25.

Jordan HayesDeveloper Relations
3 min read
How to fix
A request arrow leaves a terminal card and stops at a stopwatch. Behind it a server card sits with a spinning wait icon. A second arrow goes around, through a small retry loop, and reaches a page that reads 200.

The short answer: Puppeteer throws TimeoutError in two places: page.goto() when the page does not load in time, and waitForSelector() when the element never shows up. Both wait 30 seconds by default. Import TimeoutError from puppeteer to catch it, wait for domcontentloaded instead of the full load event, and then wait for the exact element you need. That is faster and fails for the right reason. When you do not want to run Chrome yourself, send the page to our API with the same wait: a real Chrome on our side, and an answer that runs out of time costs nothing.

What Puppeteer does on a slow server

Start a listener in one terminal with nc -lk 8799. It takes each connection and never answers, like a server that hangs. Run this in a second terminal:

sends.mjs
// npm install puppeteer
import puppeteer from "puppeteer";

const browser = await puppeteer.launch();
const page = await browser.newPage();
const t = Date.now();
try {
  await page.goto("http://127.0.0.1:8799/", { timeout: 5000 });
} catch (err) {
  console.log(err.name, "|", err.message, "| after", (Date.now() - t) / 1000, "s");
}
await browser.close();
Output
TimeoutError | Navigation timeout of 5000 ms exceeded | after 5.006 s
  • goto gave up after exactly the limit we set, 5,000 ms, with Navigation timeout of 5000 ms exceeded. Without timeout, it waits 30 seconds.
  • Chrome opened the connection and sent its request; nc never answered, so the load event never came. A slow site looks the same from here.

How Puppeteer reports a timeout

Our test store answers fast, so give it a limit too short to meet. The error is the same one a slow site gives you:

seen.mjs
// npm install puppeteer
import puppeteer, { TimeoutError } from "puppeteer";

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("https://lab.megalania.io/new-arrivals/");
try {
  await page.waitForSelector("#item-99", { timeout: 3000 });
} catch (err) {
  console.log(err.name, "|", err.message);
  console.log("is a TimeoutError:", err instanceof TimeoutError);
}
await browser.close();
Output
TimeoutError | Waiting for selector `#item-99` failed
is a TimeoutError: true
  • The page loaded fine; the element never came. The list has 12 items, so #item-99 does not exist, and waitForSelector threw after 3 seconds.
  • TimeoutError is a named export. puppeteer.TimeoutError on the default export is undefined in Puppeteer 25, so instanceof against it throws a TypeError.

The free fix: timeouts and retries

Set a limit on every request, and retry a few times with a pause. This fixes servers that are slow now and then:

fix.mjs
// npm install puppeteer
import puppeteer from "puppeteer";

const browser = await puppeteer.launch();
const page = await browser.newPage();
page.setDefaultTimeout(20000);
const t = Date.now();
await page.goto("https://lab.megalania.io/new-arrivals/", { waitUntil: "domcontentloaded" });
await page.waitForSelector("#item-12");
const names = await page.$$eval("#arrivals li h2", (els) => els.map((e) => e.textContent));
console.log(names.length, "products in", (Date.now() - t) / 1000, "s |", names[1]);
await browser.close();
Output
12 products in 1.205 s | Alpine Down Parka
  • waitUntil: "domcontentloaded" returns once the HTML is parsed, without waiting for every image and font. Then waitForSelector("#item-12") waits for the one thing this page needs: the 12th card.
  • page.setDefaultTimeout(20000) sets one limit for every wait on the page, instead of one per call.
Free beta, by invite76,000 credits for 30 days, no card. Apply, and we email your invite.Apply for the beta

The fix that climbs: our API

Send the page to our API instead. We fetch it, run a real Chrome when you ask, and an answer that runs out of time costs nothing:

fetch.mjs
// Run: MEG_API_KEY=YOUR_KEY node fetch.mjs '#item-12'
const res = await fetch("https://get.megalania.io/v1", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MEG_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://lab.megalania.io/new-arrivals/",
    engine: "browser",
    actions: `wait_for:${process.argv[2]}`,
    response_types: "json",
    extract: "items:#arrivals li{name:h2|price:.price}*",
    timeout: 20,
  }),
});
console.log("status:", res.status, "route:", res.headers.get("x-route"), "credits:", res.headers.get("x-credits-charged"));
const body = await res.json();
console.log(body.items ? `${body.items.length} products | ${JSON.stringify(body.items[1])}` : JSON.stringify(body).slice(0, 170));
Output
status: 200 route: browser/datacenter credits: 19
12 products | {"name":"Alpine Down Parka","price":"$349.00"}
  • The same wait, as one string: wait_for:#item-12. Our Chrome runs the page's script and our extract rule returns the 12 cards as JSON.
  • 19 credits: 15 for the browser, 1 for JSON and 3 for the wait. No Chrome to install or keep updated on your side.

The same call on a page whose list never finishes loading, with a 20-second limit:

Terminal
MEG_API_KEY=YOUR_KEY node fetch.mjs '#item-99'
Output
status: 422 route: null credits: null
{"error":{"code":"action_failed","field":"actions","message":"actions entry 0 could not run: no visible element matched its selector in time, or the t
  • The same missing element, on our side: our Chrome waited until the time for actions ran out, then we answered 422 action_failed.
  • credits: null: no charge header, nothing charged. Your own waitForSelector failing costs you the browser time instead.

One honest note: our test store is fast, so these runs show a short limit or a page that never gets ready, not a slow site. On a slow site, the call is the same; the price depends on the route that worked, and our MCP tool check_site tells you that price for free.

What it costs

What we ranRouteCredits
The new arrivals page, 12 products as JSON, in the browserc:dc19
The same page waiting for an element that never appearsc:dc0
sends.mjs, seen.mjs and fix.mjs, in your own Chromenone0

Every rule is in Credits. Plans are on the pricing page.

How we measured: Puppeteer 25.17.0 with its Chrome 157 on Node 24.21, one Linux server, 16 Nov 2026. nc -lk 8799 (OpenBSD netcat) as a server that never answers. Our test store for the missing selector and for fix.mjs. Our API on our dev cluster for fetch.mjs, against the same store on our dev domain. The outputs are copied from those runs.

Limits

  • Public pages only. We do not log in, and we do not solve CAPTCHAs. When a page needs either, we stop and say so, for free.
  • A page built by JavaScript needs engine=browser. It costs more. See How to scrape JavaScript-rendered pages.
  • Slow can mean slow down. A site that answers slowly may be under load. Keep your rate low, fetch public pages only, and follow the site's terms and robots.txt.

What to do when a site answers 429 instead is in 429 Too Many Requests when scraping.