Durable Sleep

Stepflow allows you to pause workflow execution for extended periods using ctx.sleep() and ctx.sleepUntil(). Unlike standard setTimeout, these delays are durable, meaning they survive worker restarts, server crashes, and deployments.

How it Works

When you call sleep, Stepflow:

1. Records the wake-up time in the storage backend.
2. Checkpoints the workflow state.
3. Stops the current execution.
4. Schedules a wake-up job in the queue.

When the wake-up time is reached, a worker picks up the job and resumes the workflow from exactly where it left off.

Sleep for a Duration

Use ctx.sleep() to pause for a specific amount of time.

await ctx.sleep("wait-for-followup", "3d");

Duration Format

Stepflow uses a human-readable duration format:

You can also pass a number representing milliseconds.

Sleep Until a Timestamp

Use ctx.sleepUntil() to pause until a specific Date.

const nextMonday = new Date("2026-01-26T09:00:00Z");
await ctx.sleepUntil("wait-for-monday", nextMonday);

Best Practices

• Unique Names: Always provide a unique name for each sleep call within a workflow. This name is used for checkpointing.
• Avoid JS Delays: Never use setTimeout or setInterval inside a workflow handler. They are not durable and will cause the workflow to fail if the worker restarts.
• Long Delays: Stepflow is designed for long-running processes. Feel free to sleep for weeks or months.