veryfront/errors

Import

import {
  attachErrorToActiveSpan,
  attachErrorToSpan,
  cliErrorBoundary,
  cliErrorBoundarySync,
  createError,
  createErrorHandler,
} from "veryfront/errors";

Examples

Define and create a structured framework error

import { defineError } from "veryfront/errors";

const INVALID_WIDGET = defineError({
  slug: "invalid-widget",
  category: "GENERAL",
  title: "Invalid widget",
  status: 400,
});
throw INVALID_WIDGET.create({ detail: "The widget id is malformed." });

Exports

Components

Name	Description	Source
`AGENT_EMPTY_RESPONSE`		source
`AGENT_ERROR`		source
`AGENT_INTENT_ERROR`		source
`AGENT_NOT_FOUND`		source
`AGENT_TIMEOUT`		source
`ALREADY_EXISTS`	Writing would replace something that is already there.	source
`API_CLIENT_ERROR`	API client request/response errors (replaces VeryfrontAPIError)	source
`API_ERROR`		source
`API_ROUTE_ERROR`		source
`ASSET_OPTIMIZATION_ERROR`		source
`AUTHENTICATION_REQUIRED`		source
`BRANCH_NOT_FOUND`		source
`BUILD_ERROR_CATALOG`		source
`BUILD_FAILED`		source
`BUNDLE_ERROR`		source
`CACHE_ERROR`		source
`CACHE_INVARIANT_VIOLATION`	Cache path invariant violations (replaces CacheInvariantError)	source
`CACHE_PATH_MISMATCH`		source
`CIRCUIT_BREAKER_OPEN`		source
`CIRCULAR_DEPENDENCY`		source
`CLIENT_BOUNDARY_VIOLATION`		source
`CLIENT_ONLY_IN_SERVER`		source
`COMPILATION_ERROR`		source
`COMPONENT_ERROR`		source
`CONFIG_ERROR_CATALOG`		source
`CONFIG_INVALID`		source
`CONFIG_NOT_DEPLOYABLE`	The project’s configuration file uses a construct Veryfront Cloud’s configuration evaluator can never accept, so the release would answer 500 to every request. Raised before a release is created; the detail names the file, the change that makes the project deployable, and the line when the evaluator located the construct it refused.	source
`CONFIG_NOT_FOUND`		source
`CONFIG_PARSE_ERROR`		source
`CONFIG_TYPE_ERROR`		source
`CONFIG_VALIDATION_ERROR`	Schema-level config validation (e.g. Zod schema mismatch at runtime)	source
`CONFIG_VALIDATION_FAILED`	Config file validation failures (replaces ConfigValidationError)	source
`CORS_CONFIG_INVALID`		source
`COST_LIMIT_EXCEEDED`		source
`DEFAULT_MODEL_CREDENTIAL_MISMATCH`	The default model’s provider has no credential while a different provider does. Resolution stays deterministic rather than silently substituting whichever key happens to be present on this machine.	source
`DEPENDENCY_MISSING`		source
`DEPENDENCY_SNAPSHOT_STORE_UNAVAILABLE`		source
`DEPLOYMENT_ERROR`		source
`DEPLOYMENT_ERROR_CATALOG`		source
`DEPLOYMENT_VERIFICATION_TIMEOUT`		source
`DEV_ERROR_CATALOG`		source
`DEV_SERVER_ERROR`		source
`DURABLE_RUN_EVENT_PERSISTENCE_FAILED`		source
`DYNAMIC_ROUTE_ERROR`		source
`ENV_VAR_MISSING`		source
`ENVIRONMENT_NOT_FOUND`		source
`ENVIRONMENT_NOT_ROUTABLE`		source
`ERROR_CATALOG`		source
`ERROR_OVERLAY_ERROR`		source
`ERROR_REGISTRY`	Central registry mapping every error slug to its definition. Assembled from the per-category registry fragments.	source
`ERROR_SOLUTIONS`		source
`ESM_CACHE_INIT_FAILED`		source
`EVAL_INFERENCE_POLICY_DENIED`	An eval stopped because a provider-executed tool is not available under the project’s EU-only inference policy.	source
`EVAL_MODEL_ACCESS_DENIED`	An eval stopped because the model gateway refused to serve its model requests for billing or entitlement reasons (HTTP 402). Every later record would fail the same way, so the run fails fast with one actionable error instead of grading empty outputs.	source
`EVAL_MODEL_EGRESS_BLOCKED`	An eval stopped because the host egress policy blocked its model gateway request: the Veryfront API host resolves to a private network address. The policy blocks every later record the same way.	source
`EVAL_MODEL_INFERENCE_POLICY_DENIED`	An eval stopped because the Veryfront Cloud gateway refused its model request under the project’s EU-only inference policy (`eu_inference_policy`). Every later record sends the same model and tools, so it is refused the same way.	source
`EVAL_MODEL_PROJECT_ACCESS_DENIED`	An eval stopped because the Veryfront Cloud gateway denied the credential access to the linked project (HTTP 403).	source
`EVAL_MODEL_SPEND_LIMIT_EXCEEDED`	An eval stopped because Veryfront reached its AI provider spend limit for the current window. Buying credits does not clear this limit.	source
`EVAL_MODEL_UNAUTHORIZED`	An eval stopped because the Veryfront Cloud gateway rejected the API credential for its model requests (HTTP 401).	source
`EVAL_PROJECT_REQUIRED`	An eval stopped because the Veryfront Cloud gateway rejected its model requests for naming no project (HTTP 400, `gateway_project_required`).	source
`EVAL_RECORD_TIMEOUT`	An eval record ran past its time limit. The limit covers the whole record: target execution, tools, model requests, metrics, and checks. A model stream that stops sending data after its response headers has no deadline of its own, so the record limit is what keeps an eval run from waiting forever.	source
`FALLBACK_EXHAUSTED`	Both primary and fallback operations failed (replaces FallbackExecutionError)	source
`FAST_REFRESH_ERROR`		source
`FILE_NOT_FOUND`		source
`FILE_WATCH_ERROR`		source
`GENERAL_ERROR_CATALOG`		source
`HMR_ERROR`		source
`HYDRATION_MISMATCH`		source
`IMPORT_MAP_INVALID`		source
`IMPORT_RESOLUTION_ERROR`		source
`INITIALIZATION_ERROR`		source
`INPUT_VALIDATION_FAILED`	HTTP request input validation failures (replaces ValidationError)	source
`INVALID_ARGUMENT`	A value the caller supplied is not acceptable: a CLI flag, a positional argument, a config field, or a function argument. Exit code 2 is the CLI’s “invalid usage” code, so a script can tell a typo from a failed run.	source
`INVALID_IMPORT`		source
`INVALID_ROUTE_FILE`		source
`INVALID_USE_CLIENT`		source
`INVALID_USE_SERVER`		source
`LAYOUT_NOT_FOUND`		source
`LOCAL_INTEGRATION_CONFIG_INVALID`		source
`LOCAL_INTEGRATION_CREDENTIAL_UNAVAILABLE`		source
`LOCAL_INTEGRATION_CREDENTIALS_MISSING`		source
`LOCAL_INTEGRATION_REQUEST_FAILED`		source
`LOCAL_INTEGRATION_REQUEST_INVALID`		source
`LOCAL_INTEGRATION_RESPONSE_INVALID`		source
`LOCKFILE_FORMAT_MISMATCH`		source
`LOCKFILE_READ_ERROR`		source
`MARKDOWN_COMPILE_ERROR`		source
`MDX_COMPILE_ERROR`		source
`MIDDLEWARE_ERROR`		source
`MODULE_ERROR_CATALOG`		source
`MODULE_NOT_FOUND`		source
`NESTED_CWD_SCOPE`	A scope that owns the process working directory was opened inside another one.	source
`NETWORK_ERROR`		source
`NOT_SUPPORTED`		source
`ORCHESTRATION_ERROR`		source
`PAGE_NOT_FOUND`		source
`PERMISSION_DENIED`		source
`PLATFORM_ERROR`		source
`PORT_IN_USE`		source
`PREVIEW_DEPLOYMENT_NOT_ALLOWED`	Veryfront’s managed Preview environment renders the latest source on the main branch. It has no release to swap, so the API refuses deployments to it.	source
`PREVIEW_HOSTNAME_TOO_LONG`		source
`PROBLEM_JSON_CONTENT_TYPE`	Content-Type header for RFC 9457 responses	source
`PRODUCTION_BUILD_REQUIRED`		source
`PROJECT_EXECUTION_UNAVAILABLE`		source
`PROJECT_LINK_STALE`	The local link in `.veryfront/project.json` names a project the control plane will not hand back. The link records no owning account, so a deleted project and one owned by a different account are indistinguishable here, so the CLI’s detail names both. Reserved for the local link: any other project reference is misdirected by a suggestion to delete this file.	source
`PROJECT_SOURCE_EMPTY`		source
`PROVIDER_REPLAY_CHECKPOINT_INVALID`	Provider replay checkpoint state failed validation at a consumer boundary. Replay state guards provider protocol correctness on resume, so malformed or unappliable state fails closed instead of degrading into an unsigned replay. Details never include checkpoint contents: provider blocks carry signed reasoning material that must stay out of logs and error text.	source
`PUSH_CONFLICT`		source
`PUSH_RECEIPT_MISSING`		source
`RAG_STORE_CORRUPT`	Persisted RAG index is malformed or failed structural validation.	source
`RAG_STORE_UNAVAILABLE`	A persisted RAG index operation could not be completed safely.	source
`REDIRECT_DESTINATION_NOT_ALLOWED`		source
`RELEASE_BUILD_TIMEOUT`		source
`RELEASE_MISSING_VERSION`		source
`RELEASE_NOT_FOUND`	Production domain resolved but no active release found	source
`RENDER_ERROR`		source
`REQUEST_ERROR`		source
`RESOURCE_NOT_FOUND`		source
`ROUTE_CONFLICT`		source
`ROUTE_ERROR_CATALOG`		source
`ROUTE_HANDLER_INVALID`		source
`ROUTE_PARAMS_ERROR`		source
`RSC_ERROR_CATALOG`		source
`RSC_PAYLOAD_ERROR`		source
`RUNTIME_ERROR_CATALOG`		source
`SCHEDULE_CONFIG_INVALID`	Schedule definition validation failures (required fields, cron, concurrencyPolicy, target)	source
`SECURITY_VIOLATION`	Path traversal / secure-fs violations (replaces SecurityError)	source
`SEMAPHORE_TIMEOUT`		source
`SERVER_ERROR_CATALOG`		source
`SERVER_ONLY_IN_CLIENT`		source
`SERVER_START_ERROR`		source
`SERVICE_OVERLOADED`		source
`SOURCE_DIGEST_MISMATCH`		source
`SOURCE_MAP_ERROR`		source
`SOURCE_SNAPSHOT_FRESHNESS_UNAVAILABLE`		source
`SOURCEMAP_ERROR`		source
`SSG_GENERATION_ERROR`		source
`SSR_OUTPUT_LIMIT_EXCEEDED`		source
`SYNC_STATE_INVALID`		source
`TEMPLATE_NOT_FOUND`	`veryfront init --template <name>` (and `npm create veryfront -- --template`) was given a name that is not in the starter catalog. The detail carries the list of valid names so a wrong guess is self-correcting.	source
`TIMEOUT_ERROR`		source
`TOKEN_STORAGE_ERROR`	Token storage adapter failures (replaces TokenStorageError)	source
`TOOL_ID_CONFLICT`		source
`TRIGGER_CONFIG_INVALID`	Trigger ID format and input serialization validation failures	source
`TRIGGER_EXECUTION_FAILED`	Trigger target task or workflow failed during local run	source
`TRIGGER_NOT_SUPPORTED`	Trigger target type is not supported in the current runtime context	source
`TRIGGER_TARGET_NOT_FOUND`	Trigger target (task or workflow) not found during local run	source
`TYPESCRIPT_ERROR`		source
`UNKNOWN_ERROR`		source
`VERSION_MISMATCH`		source
`WEBHOOK_CONFIG_INVALID`	Webhook definition validation failures (required fields, target, eventFilter)	source

Functions

Name	Description	Source
`attachErrorToActiveSpan`	Attach error to the currently active span (if any)	source
`attachErrorToSpan`	Attach error metadata to an OpenTelemetry span	source
`cliErrorBoundary`	CLI error boundary - wraps a handler function and catches errors	source
`cliErrorBoundarySync`	Synchronous version of CLI error boundary	source
`createError`		source
`createErrorHandler`	Express/Hono-style error handler middleware factory	source
`createErrorResponse`	Create an RFC 9457 compliant error Response	source
`createErrorResponseFromDefinition`	Create an RFC 9457 error Response from a registered error definition	source
`createErrorScope`	Create a scoped error context helper for multiple related operations	source
`createErrorSolution`		source
`createProblemResponse`	Create an RFC 9457 error Response from raw parameters	source
`createSimpleError`		source
`defineError`	Define an error in the registry	source
`ensureError`	Ensure a value is an Error while preserving the established identity contract for ordinary Error instances.	source
`errorToResponse`	Convert any error to an RFC 9457 Response	source
`errorToRFC9457Response`	Convert any error to an RFC 9457 Response with environment-aware filtering	source
`formatCLIError`	Format any error for CLI output	source
`formatErrorLog`	Log format for errors (matches the plan’s log format spec)	source
`formatUserError`	Format error with plain text (existing behavior)	source
`fromError`	Decode legacy Veryfront error data attached by `toError()`.	source
`getAllSlugs`	Get all registered slugs	source
`getErrorBySlug`	Get an error definition by slug	source
`getErrorMessage`	Extract error message from any error type	source
`getErrorsByCategory`	Get all errors in a category	source
`getErrorSolution`		source
`handleErrorWithFallback`		source
`handleErrorWithFallbackSync`		source
`httpErrorBoundary`	Wrap a handler with error boundary that catches all errors and converts them to RFC 9457 Problem Details responses.	source
`identifyError`		source
`isVeryfrontError`	Check if an error is a VeryfrontError with slug-based identity	source
`logError`	Log a VeryfrontError with structured formatting	source
`logErrorWithMessage`	Log an error with a custom message prefix	source
`retryWithBackoff`		source
`safeFileRead`	Safe file read with logging	source
`safeFileStat`	Safe file stat with logging	source
`safeReadDir`	Safe directory read with logging	source
`sanitizeTerminalDiagnosticText`	Prepare one untrusted diagnostic field for terminal or plain-text output. Apply framework-owned ANSI styling only after this sanitizer returns.	source
`searchErrors`		source
`toError`	Convert a VeryfrontErrorData (plain object) to a throwable Error instance.	source
`withErrorContext`	Execute async operation with error logging and fallback	source
`withErrorContextSync`	Execute sync operation with error logging and fallback	source
`wrapErrorHandler`		source
`wrapHandlerWithErrorBoundary`	Wrap a complete Handler object with error boundary	source
`wrapUnknownError`	Return a detached VeryfrontError, preserving safe identity fields from valid VeryfrontError inputs	source
`wrapWithContext`	Wrap an error with additional context	source

Classes

Name	Description	Source
`VeryfrontError`	Veryfront Error class with slug-based error identity	source

Types

Name	Description	Source
`ConfigContext`		source
`ErrorCatalog`		source
`ErrorCategory`	Error categories for domain-based grouping and handling	source
`ErrorContext`		source
`ErrorCreateOptions`	Options for creating an error instance	source
`ErrorDefinition`	Error definition for the registry	source
`ErrorHandlingOptions`		source
`ErrorLogEntry`		source
`ErrorSlug`		source
`ErrorSolution`		source
`LogLevel`		source
`PartialErrorCatalog`		source
`RegisteredError`	Registered error with factory method	source
`RetryWithBackoffOptions`	Options for `retryWithBackoff`. Every `attempt` value passed to `fn` and the hooks below is 0-based (first try = 0), including `wrapFinalError`’s `lastAttempt`.	source
`RFC9457Response`	RFC 9457 Problem Details response shape	source
`UserFriendlyErrorSolution`		source
`VeryfrontErrorData`	Discriminated union for serializable error data.	source
`VeryfrontErrorOptions`	Options for VeryfrontError constructor	source

Deep imports

These import paths group focused functionality under this module. Each is a separate barrel; import only what you need.

`veryfront/errors/general`

import { ALREADY_EXISTS, AUTHENTICATION_REQUIRED, FILE_NOT_FOUND } from "veryfront/errors/general";

Components

Name	Description	Source
`ALREADY_EXISTS`	Writing would replace something that is already there.	source
`AUTHENTICATION_REQUIRED`		source
`FILE_NOT_FOUND`		source
`GENERAL_REGISTRY`	Registry fragment for GENERAL errors (slug → definition).	source
`INITIALIZATION_ERROR`		source
`INPUT_VALIDATION_FAILED`	HTTP request input validation failures (replaces ValidationError)	source
`INVALID_ARGUMENT`	A value the caller supplied is not acceptable: a CLI flag, a positional argument, a config field, or a function argument. Exit code 2 is the CLI’s “invalid usage” code, so a script can tell a typo from a failed run.	source
`NESTED_CWD_SCOPE`	A scope that owns the process working directory was opened inside another one.	source
`NOT_SUPPORTED`		source
`PERMISSION_DENIED`		source
`PROJECT_SOURCE_EMPTY`		source
`RESOURCE_NOT_FOUND`		source
`SECURITY_VIOLATION`	Path traversal / secure-fs violations (replaces SecurityError)	source
`TIMEOUT_ERROR`		source
`UNKNOWN_ERROR`		source

`veryfront/errors/module`

import {
  CIRCULAR_DEPENDENCY,
  DEPENDENCY_MISSING,
  IMPORT_RESOLUTION_ERROR,
} from "veryfront/errors/module";

Components

Name	Description	Source
`CIRCULAR_DEPENDENCY`		source
`DEPENDENCY_MISSING`		source
`IMPORT_RESOLUTION_ERROR`		source
`INVALID_IMPORT`		source
`LOCKFILE_FORMAT_MISMATCH`		source
`LOCKFILE_READ_ERROR`		source
`MODULE_NOT_FOUND`		source
`MODULE_REGISTRY`	Registry fragment for MODULE errors (slug → definition).	source
`VERSION_MISMATCH`		source

Getting Started

Concepts

Guides

API Reference

Import

Examples

Define and create a structured framework error

Exports

Components

Functions

Classes

Types

Deep imports

`veryfront/errors/general`

Components

`veryfront/errors/module`

Components

​Import

​Examples

​Define and create a structured framework error

​Exports

​Components

​Functions

​Classes

​Types

​Deep imports

​veryfront/errors/general

​Components

​veryfront/errors/module

​Components

Import

Examples

Define and create a structured framework error

Exports

Components

Functions

Classes

Types

Deep imports

`veryfront/errors/general`

Components

`veryfront/errors/module`

Components