Implementation:Puppeteer Puppeteer Errors

Property	Value
sources	packages/puppeteer-core/src/common/Errors.ts
domains	Error Handling, Core Infrastructure
last_updated	2026-02-12 00:00 GMT

Overview

Description

Errors is a module that defines the error class hierarchy used throughout Puppeteer. All Puppeteer-specific errors extend from the base PuppeteerError class, which itself extends the native JavaScript Error. The base class automatically sets the name property to the constructor name and provides a Symbol.toStringTag getter for proper string representation.

The module defines the following error classes:

• PuppeteerError -- The base class for all Puppeteer-specific errors.
• TimeoutError -- Emitted when operations like page.waitForSelector or puppeteer.launch exceed their configured timeout.
• TouchError -- Thrown when attempting to move or end a touch that does not exist.
• ProtocolError -- Emitted when there is an error from the Chrome DevTools Protocol, with optional code and originalMessage properties.
• UnsupportedOperation -- Thrown when a method is not supported by the currently used protocol.
• TargetCloseError -- An internal error extending ProtocolError, thrown when a target is closed.
• ConnectionClosedError -- Thrown when the underlying protocol connection has been closed.

Usage

These error classes are used throughout Puppeteer to provide typed, catchable errors. Users can catch specific error types using instanceof checks to handle different failure scenarios appropriately (e.g., distinguishing between timeout errors and protocol errors).

Code Reference

Source Location

packages/puppeteer-core/src/common/Errors.ts

Signature

export class PuppeteerError extends Error {
  constructor(message?: string, options?: ErrorOptions);
  get [Symbol.toStringTag](): string;
}

export class TimeoutError extends PuppeteerError {}

export class TouchError extends PuppeteerError {}

export class ProtocolError extends PuppeteerError {
  set code(code: number | undefined);
  get code(): number | undefined;
  set originalMessage(originalMessage: string);
  get originalMessage(): string;
}

export class UnsupportedOperation extends PuppeteerError {}

export class TargetCloseError extends ProtocolError {}

export class ConnectionClosedError extends ProtocolError {}

Import

import {
  PuppeteerError,
  TimeoutError,
  TouchError,
  ProtocolError,
  UnsupportedOperation,
  TargetCloseError,
  ConnectionClosedError,
} from 'puppeteer-core/lib/esm/puppeteer/common/Errors.js';

I/O Contract

Class	Extends	Public Properties	Description
PuppeteerError	Error	name, [Symbol.toStringTag]	Base class for all Puppeteer errors
TimeoutError	PuppeteerError	(inherited)	Timeout exceeded during an operation
TouchError	PuppeteerError	(inherited)	Invalid touch operation (move/end non-existent touch)
ProtocolError	PuppeteerError	code, originalMessage	Protocol-level error from CDP or WebDriver BiDi
UnsupportedOperation	PuppeteerError	(inherited)	Method not supported by the current protocol
TargetCloseError	ProtocolError	(inherited)	Target was closed during operation
ConnectionClosedError	ProtocolError	(inherited)	Underlying protocol connection was closed

Usage Examples

import puppeteer from 'puppeteer';
import {TimeoutError, ProtocolError} from 'puppeteer';

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

try {
  // This will throw TimeoutError if the selector is not found within 5 seconds
  await page.waitForSelector('#nonexistent', {timeout: 5000});
} catch (error) {
  if (error instanceof TimeoutError) {
    console.log('Timed out waiting for selector');
  } else if (error instanceof ProtocolError) {
    console.log(`Protocol error (code: ${error.code}): ${error.originalMessage}`);
  } else {
    throw error;
  }
}

await browser.close();

Related Pages

• Environment:Puppeteer_Puppeteer_Node_18_Runtime