@vercel/error

Use structured fields to identify what failed, explain why, and suggest what to do next. Software should branch on stable fields; people and agents should read the prose. Preserve the fields until output is rendered, and never parse terminal formatting.

Workflow

1. Inspect the target project

Read the target project's package.json, lockfile, existing errors, output paths, logging, and tests before choosing an API.

• Use the installed @vercel/error version's public exports as the contract. Do not deep-import unexported source paths.
• If the package is absent, resolve the intended version from workspace constraints or the current release, then inspect its published exports and engines. Add it as a production dependency only for requested implementation work.
• Compare a Node target's version with the selected version's engines, and report an incompatibility instead of silently changing the runtime. The package itself is isomorphic (browsers, workers, edge runtimes), so treat engines as the Node support matrix, not a runtime allowlist.
• Record the project's existing code and scope names and the callers that depend on them. In step 4, preserve or challenge those conventions based on evidence.
• Leave dependencies unchanged for advice and review.

Before continuing, record the selected version and runtime compatibility, verify the public imports, and identify where the error is created, handled, sent, logged, or shown.

2. Decide whether a structured error is needed

Keep native Error for a simple local failure that no caller classifies, transports, reports, or presents with recovery guidance. Use @vercel/error when at least one of these is needed:

• a stable code or scope
• structured reason, hint, fix, or documentation
• response data or HTTP transport and reconstruction
• telemetry or debugging context
• consistent terminal presentation
• reliable recognition across bundle or realm boundaries

Use a structured error only when you can name the caller, transport, logger, or UI that needs it. "It is more consistent" is not enough.

3. Choose the public API

Need	Public API	Read
Decide error codes, details, public text, and reporting	VercelErrorOptions	Contract design
Construct one error, define a subclass, preserve a cause, or inspect a caught value	VercelError, core guards and extractors	Core errors
Create a typed family, allowlist reporting, or use a custom class	createErrors	createErrors factories
Produce or consume response data or HTTP error responses	buildErrorResponseData, errorResponse, fromHttpResponse, parseErrorResponseData, fromErrorResponseData	Response data and HTTP
Format errors for terminal output	formatError, frame, hint, fix, link	Terminal output

Use VercelError#toString() for a VercelError; it already uses the package formatter. Use frame() for errors or CLI output that should remain another type.

Read each reference whose row matches the work. Continue when every required operation maps to a public import verified in the selected package version.

4. Choose fields and recovery guidance

Apply Contract design to every field in scope, including its pushback rules.

Before implementation, verify that every populated field has a known use and every client-visible field is safe.

When set, scope and code must be nonblank. Keep their original text. Omit blank optional public fields and preserve other text.

5. Implement or review

For review work, report correctness, disclosure, and recovery gaps; edit only when asked.

For implementation, change only the error path that needs structured fields. Preserve surrounding behavior, code conventions, and third-party error types. Treat project-wide code or scope renames as a separate migration. Code examples must typecheck in the shown context or be labeled as partial replacements.

This step is complete when the reviewed or changed scope is limited to the identified use and every example is complete or explicitly partial.

6. Test public behavior

Test the behavior that consumes the error, not private formatting helpers:

• creation, throwing, and reporting through the factory when those paths matter
• stable code and preserved cause for programmatic handling
• response data with approved text and identity, excluding diagnostics
• the same public fields in JSON and ANSI, plus Content-Type, conditional Vary, and HTTP status
• rejection of invalid unknown response data before reconstruction
• terminal output with and without optional sections
• the actual public package entry point used by the target project

Run the target project's closest test and typecheck first, then its required checks. Verification is complete when they pass or every failure and untested runtime or integration path is reported.