@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 | EFAILEDEVAL | Page evaluation/script execution failed | | contextDisconnected | EBRWSRCONTEXTCONNRESET | Browser context connection was reset |

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: EFAILEDEVAL, 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.

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

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