Errors

Fix common mistakes when creating and executing workflows in the Workflow SDK.

Error codes

When a workflow run fails, its errorCode identifies the failure category. You can read it from WorkflowRunFailedError, the Workflow CLI's error.code field, or the workflow.error.code OpenTelemetry span attribute.

CodeDescription
USER_ERRORAn error thrown by workflow or step code, including an unhandled step failure or FatalError.
RUNTIME_ERRORThe Workflow runtime encountered an internal error, such as missing runtime data or an invariant failure. Persistent occurrences should be reported.
CORRUPTED_EVENT_LOGThe run's event log cannot be replayed because it contains orphaned or mismatched events, a gap, or an unreadable stored payload.
REPLAY_DIVERGENCEOne replay could not consume the event log deterministically. The runtime automatically retries before treating repeated divergence as a corrupted event log.
MAX_DELIVERIES_EXCEEDEDThe run exceeded the maximum number of queue deliveries, usually because a persistent failure kept causing redelivery.
MAX_EVENTS_EXCEEDEDThe run reached the World's per-run event limit. Run long-running workflows on the QuickJS VM with snapshotting, which is exempt from the default limit, or split unbounded work into child workflows.
REPLAY_TIMEOUTWorkflow replay exceeded the configured duration limit. This measures workflow execution and event-log replay between step boundaries, not time spent inside step functions.
STREAM_ERRORWorkflow stream infrastructure failed while reading or writing data. This is an SDK or backend failure rather than an error in workflow code.
WORLD_CONTRACT_ERRORA World returned data that violated the SDK contract and could not be retried safely. This usually indicates a World implementation bug.
DEPLOYMENT_MISMATCHA run was delivered to a deployment other than the one it is pinned to, and automatic re-routing did not recover it.
WORKFLOW_NOT_REGISTEREDThe deployment executing the run does not have the run's workflow registered, usually because the run targeted a deployment where the workflow was renamed, moved, or removed, or the build did not bundle it.

For guidance on catching failures, retry behavior, and inspecting WorkflowRunFailedError, see Errors and retries.

Troubleshooting guides

abort-signal-timeout-in-workflow

AbortSignal.timeout() cannot be used inside workflow functions because it relies on real timers which break deterministic replay.

corrupted-event-log

The workflow's event log contains an event that cannot be processed or a stored payload that cannot be read.

deployment-mismatch

A workflow run was delivered to a deployment other than the one it is pinned to.

fetch-in-workflow

Make HTTP requests from step functions instead of workflow functions.

hook-conflict

Hook tokens must be unique across all running workflows in your project.

hook-force-claimed

Another workflow run took this hook's token over with experimental_force.

max-events-exceeded

A workflow run reached the World's per-run event limit and was failed.

node-js-module-in-workflow

Move Node.js core module usage to step functions instead of workflows.

replay-divergence

A workflow replay temporarily followed a path that did not match its recorded events.

replay-timeout

Workflow replay exceeded its time budget on repeated deliveries and the run was failed.

run-expired

A run's data passed its retention boundary, so its result can no longer be read.

runtime-decryption-failed

The SDK's built-in AES-GCM encryption layer failed to encrypt or decrypt a workflow payload.

serialization-failed

Ensure all data passed between workflow and step functions is serializable.

start-invalid-workflow-function

The function passed to start() must be a transformed workflow function.

Step executed multiple times

A step ran more than once because its function invocation crashed before it could report a result.

step-not-registered

A step function is not registered in the current deployment.

timeout-in-workflow

Use the sleep function instead of setTimeout or setInterval in workflows.

webhook-invalid-respond-with-value

The respondWith option must be "manual" or a Response object.

webhook-response-not-sent

Manual webhooks must send a response before execution completes.

workflow-not-registered

A workflow function is not registered in the current deployment.

Learn more

⌂