@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
BrowserlessErrorinstances - 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: 'Printing failed' })
// => BrowserlessError: EPROTOCOL, Printing failed
// 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 (page target gone mid-evaluate)
const rawError = { message: 'Protocol error (Runtime.evaluate): Target closed' }
const normalizedError = errors.ensureError(rawError)
// => BrowserlessError: EBRWSRCONTEXTCONNRESET, The browser context is not connected.
// 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