eve
Version:
Filesystem-first framework for durable backend AI agents that run anywhere.
667 lines • 27.2 kB
TypeScript
import type { StringValue } from './_ms.js';
/**
* @internal
* All the slugs of the errors used for documentation links.
*/
export declare const ERROR_SLUGS: {
readonly NODE_JS_MODULE_IN_WORKFLOW: "node-js-module-in-workflow";
readonly START_INVALID_WORKFLOW_FUNCTION: "start-invalid-workflow-function";
readonly SERIALIZATION_FAILED: "serialization-failed";
readonly WEBHOOK_INVALID_RESPOND_WITH_VALUE: "webhook-invalid-respond-with-value";
readonly WEBHOOK_RESPONSE_NOT_SENT: "webhook-response-not-sent";
readonly FETCH_IN_WORKFLOW_FUNCTION: "fetch-in-workflow";
readonly TIMEOUT_FUNCTIONS_IN_WORKFLOW: "timeout-in-workflow";
readonly HOOK_CONFLICT: "hook-conflict";
readonly CORRUPTED_EVENT_LOG: "corrupted-event-log";
readonly REPLAY_DIVERGENCE: "replay-divergence";
readonly STEP_NOT_REGISTERED: "step-not-registered";
readonly WORKFLOW_NOT_REGISTERED: "workflow-not-registered";
readonly RUNTIME_DECRYPTION_FAILED: "runtime-decryption-failed";
readonly DEPLOYMENT_MISMATCH: "deployment-mismatch";
};
type ErrorSlug = (typeof ERROR_SLUGS)[keyof typeof ERROR_SLUGS];
interface WorkflowErrorOptions extends ErrorOptions {
/**
* The slug of the error. This will be used to generate a link to the error documentation.
*/
slug?: ErrorSlug;
}
/**
* The base class for all Workflow-related errors.
*
* This error is thrown by the Workflow SDK when internal operations fail.
* You can use this class with `instanceof` to catch any Workflow SDK error.
*
* @example
* ```ts
* try {
* await getRun(runId);
* } catch (error) {
* if (error instanceof WorkflowError) {
* console.error('Workflow SDK error:', error.message);
* }
* }
* ```
*/
export declare class WorkflowError extends Error {
readonly cause?: unknown;
constructor(message: string, options?: WorkflowErrorOptions);
static is(value: unknown): value is WorkflowError;
}
/**
* Thrown when a world (storage backend) operation fails unexpectedly.
*
* This is the catch-all error for world implementations. Specific,
* well-known failure modes have dedicated error types (e.g.
* EntityConflictError, RunExpiredError, ThrottleError). This error
* covers everything else: validation failures, missing entities
* without a dedicated type, or unexpected HTTP errors from world-vercel.
*/
export declare class WorkflowWorldError extends WorkflowError {
status?: number;
code?: string;
url?: string;
/** Retry-After value in seconds, present on 429 and 425 responses */
retryAfter?: number;
/**
* The offending argument, present on client-side validation failures
* (`code: 'INVALID_ARGUMENT'`). Lets a caller correct the specific
* parameter without parsing the message.
*/
field?: string;
constructor(message: string, options?: {
status?: number;
url?: string;
code?: string;
retryAfter?: number;
field?: string;
cause?: unknown;
});
static is(value: unknown): value is WorkflowWorldError;
}
/**
* Thrown when a workflow run fails during execution.
*
* This error indicates that the workflow encountered a fatal error and cannot
* continue. It is thrown when awaiting `run.returnValue` on a run whose status
* is `'failed'`. The `cause` property contains the underlying error with its
* message, stack trace, and optional error code.
*
* Use the static `WorkflowRunFailedError.is()` method for type-safe checking
* in catch blocks.
*
* @example
* ```ts
* import { WorkflowRunFailedError } from "workflow/internal/errors";
*
* try {
* const result = await run.returnValue;
* } catch (error) {
* if (WorkflowRunFailedError.is(error)) {
* console.error(`Run ${error.runId} failed:`, error.cause.message);
* }
* }
* ```
*/
export declare class WorkflowRunFailedError extends WorkflowError {
runId: string;
/**
* The high-level error category (e.g. USER_ERROR, RUNTIME_ERROR) for the
* failed run, from the run_failed event's `errorCode` field.
*/
errorCode?: string;
/**
* The original thrown value from the failed workflow run, hydrated through
* the workflow serialization pipeline. Preserves the original type identity
* (Error subclasses, FatalError, custom classes with WORKFLOW_SERIALIZE, etc.)
* and custom properties (cause chains, etc.).
*
* Note: any JavaScript value can be thrown, so this is typed as `unknown`.
* Typical values are Error instances, but strings, objects, etc. are also
* possible.
*/
cause: unknown;
constructor(runId: string, error: unknown, options?: {
errorCode?: string;
});
static is(value: unknown): value is WorkflowRunFailedError;
}
/**
* Thrown when attempting to get results from an incomplete workflow run.
*
* This error occurs when you try to access the result of a workflow
* that is still running or hasn't completed yet.
*/
export declare class WorkflowRunNotCompletedError extends WorkflowError {
runId: string;
status: string;
constructor(runId: string, status: string);
static is(value: unknown): value is WorkflowRunNotCompletedError;
}
/**
* Thrown when the Workflow runtime encounters an internal error.
*
* This error indicates an issue with workflow execution, such as
* serialization failures, starting an invalid workflow function, or
* other runtime problems.
*/
export declare class WorkflowRuntimeError extends WorkflowError {
constructor(message: string, options?: WorkflowErrorOptions);
static is(value: unknown): value is WorkflowRuntimeError;
}
/**
* Thrown when the persisted workflow event log cannot be replayed because it
* contains orphaned, duplicate, or mismatched events.
*
* This is a runtime/infrastructure failure rather than user code throwing.
* When this reaches run failure handling, it is recorded with the distinct
* `CORRUPTED_EVENT_LOG` code so worlds and backends can track it separately
* from generic runtime failures.
*/
export declare class CorruptedEventLogError extends WorkflowRuntimeError {
constructor(message: string, options?: ErrorOptions);
static is(value: unknown): value is CorruptedEventLogError;
}
/**
* Thrown when the current workflow replay cannot follow the path described by
* the recorded event log. A single divergence does not prove that the
* persisted history is invalid: a subsequent replay may observe or schedule
* work correctly, so the runtime may redeliver before declaring corruption.
*/
export declare class ReplayDivergenceError extends WorkflowRuntimeError {
readonly eventId: string;
constructor(message: string, options: ErrorOptions & {
eventId: string;
});
static is(value: unknown): value is ReplayDivergenceError;
}
/**
* Thrown when a run's event log reaches the server-supplied per-run event
* ceiling. Classified as `MAX_EVENTS_EXCEEDED` (see `classifyRunError`).
*/
export declare class MaxEventsExceededError extends WorkflowError {
readonly eventCount: number;
readonly limit: number;
constructor(eventCount: number, limit: number, options?: WorkflowErrorOptions);
static is(value: unknown): value is MaxEventsExceededError;
}
/**
* Optional structured context attached to a {@link RuntimeDecryptionError},
* carried over from the underlying decrypt call site to help diagnose the
* failure without poking through stacks.
*/
export interface RuntimeDecryptionErrorContext {
/** The operation that failed, useful to tell encrypt vs decrypt apart. */
operation?: 'encrypt' | 'decrypt';
/** Byte length of the input payload at the time of the failure. */
byteLength?: number;
/**
* The first 4 bytes of the input payload, decoded as UTF-8 if printable.
* Useful for telling apart truncated-but-valid-looking encrypted payloads
* from completely unrelated corruption (e.g. an HTML error page surfaced
* as a 200 OK).
*/
formatPrefix?: string;
}
/**
* Thrown when the SDK's built-in AES-GCM encryption layer fails to encrypt
* or decrypt a workflow payload.
*
* This is an internal SDK failure: user code never invokes the SDK's
* encryption primitives directly. Common causes:
*
* - A ciphertext / auth tag mismatch, typically surfaced as the native Web
* Crypto `OperationError: The operation failed for an operation-specific
* reason`. Usually caused by ciphertext mutation or truncation in transit
* between storage and read (truncated HTTP response, edge-cache miss
* returning a partial 200, proxy drop during streaming, etc.).
* - A key resolution mismatch (wrong deployment, missing key material).
* - A malformed encrypted envelope (too short to contain the GCM nonce
* and tag).
*
* Extends {@link WorkflowRuntimeError} so the run-failure classifier
* routes it to `RUNTIME_ERROR`.
*/
export declare class RuntimeDecryptionError extends WorkflowRuntimeError {
/** Optional structured context about the failed encrypt/decrypt call. */
readonly context?: RuntimeDecryptionErrorContext;
constructor(message: string, options?: ErrorOptions & {
context?: RuntimeDecryptionErrorContext;
});
static is(value: unknown): value is RuntimeDecryptionError;
}
interface WorkflowBuildErrorOptions extends ErrorOptions {
/**
* An optional actionable hint appended to the main message, explaining how
* the user can resolve the failure. Shown after a blank line.
*/
hint?: string;
}
/**
* Thrown when the workflow build pipeline (esbuild, SWC transform, file
* discovery, bundler integration) fails in a way the user can act on.
*
* This is distinct from `WorkflowRuntimeError` (which is raised at runtime
* by the workflow engine): `WorkflowBuildError` fires during `pnpm build`,
* `next build`, or equivalent, before any workflow has started executing.
*
* Prefer attaching a short, actionable `hint` (e.g. `run \`pnpm install workflow\``)
* as plain text; the rendering layer is responsible for any styling or
* "hint:" label. Keeping `hint` plain keeps it useful in non-TTY contexts
* (CI logs, structured error serialization) where ANSI escapes are noise.
*/
export declare class WorkflowBuildError extends WorkflowError {
readonly hint?: string;
constructor(message: string, options?: WorkflowBuildErrorOptions);
static is(value: unknown): value is WorkflowBuildError;
}
interface SerializationErrorOptions extends ErrorOptions {
/**
* An optional actionable hint appended to the main message, explaining how
* the user can resolve the failure (e.g. "register the class with…" or
* "move this call inside a step").
*/
hint?: string;
}
/**
* Thrown when a value cannot be serialized into or deserialized out of the
* workflow event log.
*
* This usually indicates a user-facing mistake: passing a non-serializable
* value (class without `WORKFLOW_SERIALIZE`, locked stream, direct workflow
* function reference) into a step boundary, or an unregistered class
* returning from a step.
*
* Internal invariants (corrupted buffers, unknown format bytes) should use
* `WorkflowRuntimeError` instead; this class is scoped to things the user
* can fix in their own code.
*/
export declare class SerializationError extends WorkflowError {
readonly hint?: string;
/**
* Serialization errors are deterministic: if a step returns a non-POJO,
* replaying the step will always produce the same non-serializable value.
* Retrying is guaranteed to fail, so these errors are surfaced as fatal
* and skip the step-retry loop. `FatalError.is()` recognizes any error
* with `fatal: true` (see `packages/errors/src/index.ts`), so no other
* wiring is required for user-thrown SerializationErrors.
*/
readonly fatal = true;
constructor(message: string, options?: SerializationErrorOptions);
static is(value: unknown): value is SerializationError;
}
/**
* Thrown when a step function is not registered in the current deployment.
*
* This is an infrastructure error, not a user code error. It typically means
* something went wrong with the bundling/build tooling that caused the step
* to not get built correctly.
*
* When this happens, the step fails (like a FatalError) and control is passed back
* to the workflow function, which can optionally handle the failure gracefully.
*/
export declare class StepNotRegisteredError extends WorkflowRuntimeError {
stepName: string;
constructor(stepName: string);
static is(value: unknown): value is StepNotRegisteredError;
}
/**
* Thrown when a workflow function is not registered in the current deployment.
*
* This is an infrastructure error, not a user code error. It typically means:
* - A run was started against a deployment that does not have the workflow
* (e.g., the workflow was renamed or moved and a new run targeted the latest deployment)
* - Something went wrong with the bundling/build tooling that caused the workflow
* to not get built correctly
*
* When this happens, the run fails with a `RUNTIME_ERROR` error code.
*/
export declare class WorkflowNotRegisteredError extends WorkflowRuntimeError {
workflowName: string;
constructor(workflowName: string);
static is(value: unknown): value is WorkflowNotRegisteredError;
}
/**
* Thrown when a workflow run is delivered to a deployment other than the one
* it is pinned to.
*
* A run is pinned to one deployment when it starts, and executing anywhere
* else is unsafe: that deployment's bundles may not match the run's history.
*/
export declare class WorkflowDeploymentMismatchError extends WorkflowRuntimeError {
readonly runId: string;
readonly expectedDeploymentId: string;
readonly actualDeploymentId: string;
/**
* How many times the runtime re-routed the message before giving up. `0`
* means recovery was never attempted: the budget is disabled, or the
* re-route itself failed and `cause` holds the enqueue error.
*/
readonly recoveryAttempts: number;
constructor(runId: string, expectedDeploymentId: string, actualDeploymentId: string, options?: {
recoveryAttempts?: number;
cause?: unknown;
});
static is(value: unknown): value is WorkflowDeploymentMismatchError;
}
/**
* Thrown when performing operations on a workflow run that does not exist.
*
* This error occurs when you call methods on a run object (e.g. `run.status`,
* `run.cancel()`, `run.returnValue`) but the underlying run ID does not match
* any known workflow run. Note that `getRun(id)` itself is synchronous and will
* not throw; this error is raised when subsequent operations discover the run
* is missing.
*
* Use the static `WorkflowRunNotFoundError.is()` method for type-safe checking
* in catch blocks.
*
* @example
* ```ts
* import { WorkflowRunNotFoundError } from "workflow/internal/errors";
*
* try {
* const status = await run.status;
* } catch (error) {
* if (WorkflowRunNotFoundError.is(error)) {
* console.error(`Run ${error.runId} does not exist`);
* }
* }
* ```
*/
export declare class WorkflowRunNotFoundError extends WorkflowError {
runId: string;
constructor(runId: string);
static is(value: unknown): value is WorkflowRunNotFoundError;
}
/**
* Thrown when a hook token is already in use by another active workflow run.
*
* This is a user error: it means the same custom token was passed to
* `createHook` in two or more concurrent runs. Use a unique token per run
* (or omit the token to let the runtime generate one automatically).
*/
export declare class HookConflictError extends WorkflowError {
token: string;
conflictingRunId?: string;
constructor(token: string, conflictingRunId?: string);
static is(value: unknown): value is HookConflictError;
}
/**
* Thrown when calling `resumeHook()` or `resumeWebhook()` with a token that
* does not match any active hook.
*
* Common causes:
* - The hook has expired (past its TTL)
* - The hook was already disposed after being consumed
* - The workflow has not started yet, so the hook does not exist
*
* A common pattern is to catch this error and start a new workflow run when
* the hook does not exist yet (the "resume or start" pattern).
*
* Use the static `HookNotFoundError.is()` method for type-safe checking in
* catch blocks.
*
* @example
* ```ts
* import { HookNotFoundError } from "workflow/internal/errors";
*
* try {
* await resumeHook(token, payload);
* } catch (error) {
* if (HookNotFoundError.is(error)) {
* // Hook doesn't exist, so start a new workflow run instead
* await startWorkflow("myWorkflow", payload);
* }
* }
* ```
*/
export declare class HookNotFoundError extends WorkflowError {
token: string;
constructor(token: string);
static is(value: unknown): value is HookNotFoundError;
}
/**
* Thrown when an operation conflicts with the current state of an entity.
* This includes attempts to modify an entity already in a terminal state,
* create an entity that already exists, or any other 409-style conflict.
*
* The workflow runtime handles this error automatically. Users interacting
* with world storage backends directly may encounter it.
*/
export declare class EntityConflictError extends WorkflowWorldError {
constructor(message: string);
static is(value: unknown): value is EntityConflictError;
}
/**
* Thrown when a run is no longer available, either because it has been
* cleaned up, expired, or already reached a terminal state (completed/failed).
*
* Also thrown by `await run.returnValue` when the run's data passed its
* retention boundary — because it was started with
* `experimental_retention: 0`, or simply because it aged out of the World's
* default window. The run's metadata usually outlives its payloads, so
* `runStatus` and `expiredAt` are populated when the World still has them: the
* caller can tell "it succeeded, but the result is gone" from "it failed".
* When even the metadata is gone the World reports the run as missing and you
* get {@link WorkflowRunNotFoundError} instead.
*
* This is terminal. Retrying cannot bring the data back.
*/
export declare class RunExpiredError extends WorkflowWorldError {
/** The run whose data expired, when the caller knew it. */
readonly runId?: string | undefined;
/**
* The run's terminal status, when its metadata outlived its payloads.
* Lets a caller distinguish a successful run whose result is gone from a
* failed one whose error is gone.
*
* Named `runStatus` rather than `status` because the base
* {@link WorkflowWorldError} already carries the HTTP `status`.
*/
readonly runStatus?: string | undefined;
/** When the data passed its retention boundary, if the World reports it. */
readonly expiredAt?: Date | undefined;
constructor(message: string,
/** The run whose data expired, when the caller knew it. */
runId?: string | undefined,
/**
* The run's terminal status, when its metadata outlived its payloads.
* Lets a caller distinguish a successful run whose result is gone from a
* failed one whose error is gone.
*
* Named `runStatus` rather than `status` because the base
* {@link WorkflowWorldError} already carries the HTTP `status`.
*/
runStatus?: string | undefined,
/** When the data passed its retention boundary, if the World reports it. */
expiredAt?: Date | undefined);
static is(value: unknown): value is RunExpiredError;
}
/**
* Thrown when Workflow's stream infrastructure fails to read or write data.
* The failure is attributable to the Workflow service rather than user code.
*/
export declare class StreamError extends WorkflowWorldError {
constructor(message: string, options?: {
cause?: unknown;
url?: string;
status?: number;
});
static is(value: unknown): value is StreamError;
}
/**
* Thrown when a stream is no longer readable because its owning run passed its
* storage-retention boundary. This is terminal: retrying cannot restore data.
*
* Unlike {@link RunExpiredError}, this identifies the failed stream read and
* exposes the server's authoritative expiry timestamp for user-facing errors.
*/
export declare class StreamExpiredError extends WorkflowWorldError {
readonly runId?: string | undefined;
readonly streamId?: string | undefined;
readonly expiredAt?: Date | undefined;
constructor(message: string, runId?: string | undefined, streamId?: string | undefined, expiredAt?: Date | undefined);
static is(value: unknown): value is StreamExpiredError;
}
/**
* Thrown when an operation cannot proceed because a required timestamp
* (e.g. retryAfter) has not been reached yet.
*
* The workflow runtime handles this error automatically. Users interacting
* with world storage backends directly may encounter it.
*
* @property retryAfter - Delay in seconds before the operation can be retried.
*/
export declare class TooEarlyError extends WorkflowWorldError {
constructor(message: string, options?: {
retryAfter?: number;
});
static is(value: unknown): value is TooEarlyError;
}
/**
* Thrown when a request is rate limited by the workflow backend.
*
* The workflow runtime handles this error automatically with retry logic.
* Users interacting with world storage backends directly may encounter it
* if retries are exhausted.
*
* @property retryAfter - Delay in seconds before the request can be retried.
*/
export declare class ThrottleError extends WorkflowWorldError {
retryAfter?: number;
constructor(message: string, options?: {
retryAfter?: number;
});
static is(value: unknown): value is ThrottleError;
}
/**
* Thrown when the backend rejects an event creation because the client's
* event-log snapshot is stale: the log the client replayed from is missing
* an event the backend has already recorded (HTTP 412).
*
* The workflow runtime handles this automatically: it restarts the replay from
* a corrected event log, ultimately re-enqueueing the run if it cannot catch
* up. Users interacting with world storage backends directly may encounter it.
*
* @property retryAfter - Delay in seconds before retrying. Accepted for
* forward-compatibility; the runtime restarts its replay immediately and
* does not read this field.
* @property details - Optional rejection detail supplied by the World. A World
* MAY attach the events the client's snapshot was missing so the client can
* correct its log without a follow-up fetch. The attached set must account
* for the whole discrepancy the rejection reported or be omitted entirely; a
* client that receives nothing does the authoritative full reload, which is
* always correct. Typed `unknown` because this package cannot depend
* on the event type; consumers narrow it themselves and must treat a
* missing or malformed value as "no detail" (a full reload is always
* correct).
*/
export declare class PreconditionFailedError extends WorkflowWorldError {
readonly details?: unknown;
constructor(message: string, options?: {
retryAfter?: number;
details?: unknown;
});
static is(value: unknown): value is PreconditionFailedError;
}
/**
* Thrown when awaiting `run.returnValue` on a workflow run that was cancelled.
*
* This error indicates that the workflow was explicitly cancelled (via
* `run.cancel()`) and will not produce a return value. You can check for
* cancellation before awaiting the return value by inspecting `run.status`.
*
* Use the static `WorkflowRunCancelledError.is()` method for type-safe
* checking in catch blocks.
*
* @example
* ```ts
* import { WorkflowRunCancelledError } from "workflow/internal/errors";
*
* try {
* const result = await run.returnValue;
* } catch (error) {
* if (WorkflowRunCancelledError.is(error)) {
* console.log(`Run ${error.runId} was cancelled`);
* }
* }
* ```
*/
export declare class WorkflowRunCancelledError extends WorkflowError {
runId: string;
constructor(runId: string);
static is(value: unknown): value is WorkflowRunCancelledError;
}
/**
* Thrown when attempting to operate on a workflow run that requires a newer World version.
*
* This error occurs when a run was created with a newer spec version than the
* current World implementation supports. To resolve this, upgrade your
* `workflow` packages to a version that supports the required spec version.
*
* Use the static `RunNotSupportedError.is()` method for type-safe checking in
* catch blocks.
*
* @example
* ```ts
* import { RunNotSupportedError } from "workflow/internal/errors";
*
* try {
* const status = await run.status;
* } catch (error) {
* if (RunNotSupportedError.is(error)) {
* console.error(
* `Run requires spec v${error.runSpecVersion}, ` +
* `but world supports v${error.worldSpecVersion}`
* );
* }
* }
* ```
*/
export declare class RunNotSupportedError extends WorkflowError {
readonly runSpecVersion: number;
readonly worldSpecVersion: number;
constructor(runSpecVersion: number, worldSpecVersion: number);
static is(value: unknown): value is RunNotSupportedError;
}
/**
* A fatal error is an error that cannot be retried.
* It will cause the step to fail and the error will
* be bubbled up to the workflow logic.
*
* Any error can opt into the non-retry behavior by setting a `fatal: true`
* own property. This is how structured error classes that aren't direct
* `FatalError` subclasses (e.g. context-violation errors) signal to the
* step executor that retrying will never help (the user's code is calling
* a workflow-only API from the wrong context, or similar) and burning
* retry attempts produces a wall of duplicated log output.
*/
export declare class FatalError extends Error {
fatal: boolean;
constructor(message: string);
static is(value: unknown): value is FatalError;
}
export interface RetryableErrorOptions {
/**
* The number of milliseconds to wait before retrying the step.
* Can also be a duration string (e.g., "5s", "2m") or a Date object.
* If not provided, the step will be retried after 1 second (1000 milliseconds).
*/
retryAfter?: number | StringValue | Date;
}
/**
* An error that can happen during a step execution, allowing
* for configuration of the retry behavior.
*/
export declare class RetryableError extends Error {
/**
* The Date when the step should be retried.
*/
retryAfter: Date;
constructor(message: string, options?: RetryableErrorOptions);
static is(value: unknown): value is RetryableError;
}
export declare const VERCEL_403_ERROR_MESSAGE = "Your current vercel account does not have access to this resource. Use `vercel login` or `vercel switch` to ensure you are linked to the right account.";
export { RUN_ERROR_CODES, type RunErrorCode } from './error-codes.js';
//# sourceMappingURL=index.d.ts.map