browserless browserless

Powered by microlink.io Last version Coverage Status NPM Status

> @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)