@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

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.

// 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