{"id":12352,"library":"verror","title":"VError: Rich JavaScript Error Handling","description":"The `verror` library, currently at stable version 1.10.1, provides a set of robust error classes designed for creating richer, more debuggable JavaScript errors. Its core strength lies in implementing Joyent's best practices for error handling, offering features like `printf`-style message formatting for clear, human-readable errors, and sophisticated error chaining. `VError` allows chaining errors while preserving messages from all layers of the call stack, providing a comprehensive diagnostic trail. Conversely, `WError` wraps and chains errors but hides lower-level messages from the top-level error, making it suitable for public API endpoints where internal details should be obscured. The library also includes `SError` for stricter `printf` argument validation and `MultiError` for aggregating errors from parallel operations. While highly functional, its release cadence is slow, with the last major update being several years ago, and it primarily targets CommonJS environments, lacking native ESM support. This makes it a mature, stable choice, though potentially requiring adaptation for modern JavaScript module systems.","status":"maintenance","version":"1.10.1","language":"javascript","source_language":"en","source_url":"https://github.com/joyent/node-verror","tags":["javascript","error","errors","err","exception","exceptions","custom"],"install":[{"cmd":"npm install verror","lang":"bash","label":"npm"},{"cmd":"yarn add verror","lang":"bash","label":"yarn"},{"cmd":"pnpm add verror","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"VError is the primary error class and is the main export object in CommonJS. Other classes like WError and MultiError are accessed as properties of this object.","wrong":"import { VError } from 'verror';","symbol":"VError","correct":"const VError = require('verror');"},{"note":"WError is a property of the main 'verror' export. It wraps errors but, unlike VError, hides inner messages by default from the top-level error message for API privacy.","wrong":"import { WError } from 'verror';","symbol":"WError","correct":"const VError = require('verror');\nconst WError = VError.WError;"},{"note":"MultiError is a property of the main 'verror' export. It is used to encapsulate one or more other errors, commonly for handling results from parallel operations.","wrong":"import { MultiError } from 'verror';","symbol":"MultiError","correct":"const VError = require('verror');\nconst MultiError = VError.MultiError;"}],"quickstart":{"code":"const VError = require('verror');\nconst fs = require('fs');\nconst filename = '/path/to/nonexistent_file_example'; // Ensure this file path does not exist for the example\n\nfs.stat(filename, function (err1) {\n    if (err1) {\n        // Wrap the original filesystem error with specific context\n        const err2 = new VError(err1, 'Failed to retrieve stats for file \"%s\"', filename);\n        \n        // Further wrap with a higher-level operational context\n        const err3 = new VError(err2, 'Critical system operation failed during file access');\n\n        console.error('Full nested error message:', err3.message);\n        // Expected output: Critical system operation failed during file access: Failed to retrieve stats for file \"/path/to/nonexistent_file_example\": ENOENT, stat '/path/to/nonexistent_file_example'\n\n        console.error('Immediate cause of err3:', err3.cause().message);\n        // Expected output: Immediate cause of err3: Failed to retrieve stats for file \"/path/to/nonexistent_file_example\": ENOENT, stat '/path/to/nonexistent_file_example'\n\n        console.error('Original underlying error:', err3.cause().cause().message);\n        // Expected output: Original underlying error: ENOENT, stat '/path/to/nonexistent_file_example'\n\n        // Example of adding custom informational properties\n        const detailedError = new VError({\n            cause: err3,\n            name: 'FileOperationError',\n            info: {\n                requestedPath: filename,\n                operationType: 'readStats',\n                timestamp: new Date().toISOString()\n            }\n        }, 'Comprehensive error for logging');\n        console.error('Error info properties:', detailedError.info);\n    } else {\n        console.log(`File ${filename} exists. This example requires a non-existent file.`);\n    }\n});","lang":"javascript","description":"Demonstrates VError's core features including printf-style messages, error chaining, accessing underlying causes, and attaching informational properties, using a file system operation as an example."},"warnings":[{"fix":"Strictly use CommonJS `require()` syntax. For new projects requiring native ESM, consider alternative error handling libraries or a CommonJS wrapper.","message":"CommonJS-only Module System. `verror` versions up to 1.10.1 are designed exclusively for CommonJS (`require()`). Attempting to use ES module `import` syntax will fail directly or require transpilation/bundler configuration, which might not be straightforward in all modern ESM-first environments.","severity":"gotcha","affected_versions":"<=1.10.1"},{"fix":"Understand the distinction between `VError` (full chain in message) and `WError` (top-level message only). To access full details with `WError`, use `err.fullStack()` or `err.cause()` to traverse the chain programmatically.","message":"`WError` Masks Inner Messages by Default. Unlike `VError`, `WError` is designed to hide the messages of its causal errors from the primary `message` property. While useful for public APIs, this can lead to confusion if developers expect `WError` to behave like `VError` and expose the full error chain in the top-level message.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"Carefully match format specifiers with the corresponding arguments. Ensure the correct number and type of arguments are provided for each specifier in the format string.","message":"Strict `printf`-style Formatting. `VError` and `SError` constructors use `printf`-style arguments for messages. If the number or type of format specifiers (e.g., `%s`, `%d`) does not match the provided arguments, it can lead to runtime errors or unexpected messages.","severity":"gotcha","affected_versions":">=1.0"},{"fix":"For new projects, evaluate if alternatives offering more active maintenance and modern features are more suitable. For existing projects, be aware of its static nature regarding new features or ecosystem changes.","message":"Library Maturity and Maintenance. The `verror` package (v1.10.1) has not been actively developed for several years. While stable and functional, it may not receive updates for new Node.js features, security vulnerabilities, or modern JavaScript ecosystem best practices.","severity":"gotcha","affected_versions":"<=1.10.1"},{"fix":"Implement a helper function to traverse the cause chain (e.g., a `while` loop or recursive function) to find a specific cause or collect all causes, reducing verbose access.","message":"Verbosity in Accessing Deeply Nested Causes. Retrieving a specific error from a long chain often requires multiple, repetitive calls to `err.cause().cause()...`. There's no built-in utility for direct access by depth or type within the VError API.","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure the error object is an instance of a `verror` class and was explicitly created with a `cause`. Use `VError.hasCause(err)` to safely check if an error object has a cause before attempting to access it.","cause":"Attempting to call `.cause()` on an object that is not an instance of `VError`, `WError`, or `SError`, or on an error that was not constructed with a `cause` argument.","error":"TypeError: err.cause is not a function"},{"fix":"Review the format string in the error constructor and ensure there is a corresponding argument for each format specifier. For example, `new VError('Hello %s')` requires one string argument after the message.","cause":"When constructing a `VError` or `SError` with a `printf`-style message, the number of format specifiers (e.g., `%s`, `%d`) does not match the number of subsequent arguments provided for interpolation.","error":"RangeError: Too few arguments for format string"},{"fix":"Use the CommonJS `require` syntax: `const VError = require('verror');` for the primary class. Other classes like `WError` are accessed as properties (e.g., `VError.WError`). The package does not natively support ESM imports.","cause":"Attempting to use `VError` with ES module `import` syntax (`import { VError } from 'verror';`) or an incorrect CommonJS `require` statement. This library is CommonJS-first.","error":"ReferenceError: VError is not defined"}],"ecosystem":"npm"}