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.
| Code | Description |
|---|---|
USER_ERROR | An error thrown by workflow or step code, including an unhandled step failure or FatalError. |
RUNTIME_ERROR | The Workflow runtime encountered an internal error, such as missing runtime data or an invariant failure. Persistent occurrences should be reported. |
CORRUPTED_EVENT_LOG | The run's event log cannot be replayed because it contains orphaned or mismatched events, a gap, or an unreadable stored payload. |
REPLAY_DIVERGENCE | One replay could not consume the event log deterministically. The runtime automatically retries before treating repeated divergence as a corrupted event log. |
MAX_DELIVERIES_EXCEEDED | The run exceeded the maximum number of queue deliveries, usually because a persistent failure kept causing redelivery. |
MAX_EVENTS_EXCEEDED | The 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_TIMEOUT | Workflow replay exceeded the configured duration limit. This measures workflow execution and event-log replay between step boundaries, not time spent inside step functions. |
STREAM_ERROR | Workflow stream infrastructure failed while reading or writing data. This is an SDK or backend failure rather than an error in workflow code. |
WORLD_CONTRACT_ERROR | A World returned data that violated the SDK contract and could not be retried safely. This usually indicates a World implementation bug. |
DEPLOYMENT_MISMATCH | A run was delivered to a deployment other than the one it is pinned to, and automatic re-routing did not recover it. |
WORKFLOW_NOT_REGISTERED | The 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
- API Reference - Complete API documentation
- Foundations - Architecture and core concepts
- Examples - Sample implementations
- GitHub Issues - Report bugs and request features