@browserless/errors: A collection of qualified errors for Puppeteer.

Install

Using npm:

npm install @browserless/errors --save

About

This package provides standardized, qualified error types for Puppeteer and browserless operations. It normalizes raw browser errors into consistent, typed errors with unique error codes for easier debugging and error handling.

What this package does

The @browserless/errors package allows you to:

• Create typed errors with consistent structure and error codes
• Normalize raw errors from Puppeteer into qualified BrowserlessError instances
• Identify error types programmatically using error codes
• Debug errors with built-in serialization and logging

Error Types

| Error Factory | Code | Description | |---------------|------|-------------| | browserTimeout | EBRWSRTIMEOUT | Promise or navigation timed out | | protocolError | EPROTOCOL | Chrome DevTools Protocol error | | evaluationFailed | EINVALEVAL | Page evaluation/script execution failed | | contextDisconnected | EBRWSRCONTEXTCONNRESET | Browser context connection was reset | | pageRange | EPAGERANGE | printToPDF was given a page range starting past the end of the document |

Codes carry retryability: the core retries EPROTOCOL and EBRWSRCONTEXTCONNRESET, and nothing else. EPAGERANGE exists because an unsatisfiable page range is the one protocol failure that is deterministic — retrying it burns the caller's budget and surfaces a timeout instead of the real reason.

Usage

const errors = require('@browserless/errors')

// Create a timeout error
const timeoutError = errors.browserTimeout({ timeout: 30000 })
// => BrowserlessError: EBRWSRTIMEOUT, Promise timed out after 30000 milliseconds

// Create a protocol error
const protocolError = errors.protocolError({ message: 'Target closed.' })
// => BrowserlessError: EPROTOCOL, Target closed.

// Create an evaluation error
const evalError = errors.evaluationFailed({ message: 'foo is not defined' })
// => BrowserlessError: EINVALEVAL, foo is not defined

// Normalize a raw error from Puppeteer
const rawError = { message: 'Protocol error (Runtime.callFunctionOn): Target closed.' }
const normalizedError = errors.ensureError(rawError)
// => BrowserlessError: EPROTOCOL, Target closed.

// Normalize a page range Chrome cannot satisfy
const rangeError = errors.ensureError({
  message: 'Protocol error (Page.printToPDF): Page range exceeds page count'
})
// => BrowserlessError: EPAGERANGE, Page range exceeds page count

// Check if an error is a BrowserlessError
if (errors.isBrowserlessError(normalizedError)) {
  console.log('Error code:', normalizedError.code)
}

Two predicates are exported for classifying a raw error before it is normalized:

errors.isContextDestroyed(rawError)    // frame torn down mid-flight — transient
errors.isPageRangeOvershoot(rawError)  // range starts past the last page — deterministic

Error properties

All BrowserlessError instances include:

| Property | Description | |----------|-------------| | name | Always 'BrowserlessError' | | code | Unique error code (e.g., EBRWSRTIMEOUT) | | message | Human-readable error message prefixed with the code |

How it fits in the monorepo

This is a foundational utility package used throughout the browserless ecosystem:

| Consumer | Purpose | |----------|---------| | browserless (core) | Wraps operations with timeout errors, normalizes caught errors | | @browserless/goto | Handles navigation and protocol errors | | @browserless/screenshot | Handles screenshot capture errors | | @browserless/pdf | Handles PDF generation errors |

Dependencies

| Package | Purpose | |---------|---------| | whoops | Error factory for creating typed errors with codes | | ensure-error | Ensures values are proper Error instances | | serialize-error | Serializes errors for debug logging | | debug-logfmt | Structured debug logging |

License

@browserless/errors © Microlink, released under the MIT License. Authored and maintained by Microlink with help from contributors.

The logo has been designed by xinh studio.

microlink.io · GitHub microlinkhq · X @microlinkhq