eve/dist/src/compiled/@workflow/errors/index.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

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";
};
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;
    constructor(message: string, options?: {
        status?: number;
        url?: string;
        code?: string;
        retryAfter?: number;
        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;
}
/**
 * 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 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 — 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).
 *
 * The workflow runtime handles this error automatically. Users interacting
 * with world storage backends directly may encounter it.
 */
export declare class RunExpiredError extends WorkflowWorldError {
    constructor(message: string);
    static is(value: unknown): value is RunExpiredError;
}
/**
 * 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 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 handler 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 just 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