> @browserless/errors: A collection of qualified errors for Puppeteer.
## Install
Using npm:
```sh
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
```js
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:
```js
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](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.
Authored and maintained by [Microlink](https://microlink.io) with help from [contributors](https://github.com/microlinkhq/browserless/contributors).
The [logo](https://thenounproject.com/term/browser/288309/) has been designed by [xinh studio](https://xinh.studio).
> [microlink.io](https://microlink.io) · GitHub [microlinkhq](https://github.com/microlinkhq) · X [@microlinkhq](https://x.com/microlinkhq)