Rules of Workflows

Rules of Workflows

Last updated Oct 15, 2026 A Workflow contains one or more steps. Each step is a self-contained, individually retryable component of a Workflow. Steps may emit (optional) state that allows a Workflow to persist and continue from that step, even if a Workflow fails due to a network or infrastructure issue.

This is a small guidebook on how to build more resilient and correct Workflows.

Ensure API/Binding calls are idempotent

Because a step might be retried multiple times, your steps should (ideally) be idempotent. For context, idempotency is a logical property where the operation (in this case a step), can be applied multiple times without changing the result beyond the initial application.

As an example, let us assume you have a Workflow that charges your customers, and you really do not want to charge them twice by accident. Before charging them, you should check if they were already charged:

index.jsjs

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event, step) {
        const customer_id = 123456;
        // ✅ Good: Non-idempotent API/Binding calls are always done **after** checking if the operation is
        // still needed.
        await step.do(
            `charge ${customer_id} for its monthly subscription`,
            async () => {
                // API call to check if customer was already charged
                const subscription = await fetch(
                    `https://payment.processor/subscriptions/${customer_id}`,
                ).then((res) => res.json());

// return early if the customer was already charged, this can happen if the destination service dies
                // in the middle of the request but still commits it, or if the Workflows Engine restarts.
                if (subscription.charged) {
                    return;
                }

// non-idempotent call, this operation can fail and retry but still commit in the payment
                // processor - which means that, on retry, it would mischarge the customer again if the above checks
                // were not in place.
                return await fetch(
                    `https://payment.processor/subscriptions/${customer_id}`,
                    {
                        method: "POST",
                        body: JSON.stringify({ amount: 10.0 }),
                    },
                );
            },
        );
    }
}

index.tsts

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
        const customer_id = 123456;
        // ✅ Good: Non-idempotent API/Binding calls are always done **after** checking if the operation is
        // still needed.
        await step.do(
            `charge ${customer_id} for its monthly subscription`,
            async () => {
                // API call to check if customer was already charged
                const subscription = await fetch(
                    `https://payment.processor/subscriptions/${customer_id}`,
                ).then((res) => res.json());

// return early if the customer was already charged, this can happen if the destination service dies
                // in the middle of the request but still commits it, or if the Workflows Engine restarts.
                if (subscription.charged) {
                    return;
                }

// non-idempotent call, this operation can fail and retry but still commit in the payment
                // processor - which means that, on retry, it would mischarge the customer again if the above checks
                // were not in place.
                return await fetch(
                    `https://payment.processor/subscriptions/${customer_id}`,
                    {
                        method: "POST",
                        body: JSON.stringify({ amount: 10.0 }),
                    },
                );
            },
        );
    }
}

Note

Guaranteeing idempotency might be optional in your specific use-case and implementation, but we recommend that you always try to guarantee it.

Make your steps granular

Steps should be as self-contained as possible. This allows your own logic to be more durable in case of failures in third-party APIs, network errors, and so on.

You can also think of it as a transaction, or a unit of work.

✅ Minimize the number of API/binding calls per step (unless you need multiple calls to prove idempotency).

index.jsjs

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event, step) {
        // ✅ Good: Unrelated API/Binding calls are self-contained, so that in case one of them fails
        // it can retry them individually. It also has an extra advantage: you can control retry or
        // timeout policies for each granular step - you might not to want to overload http.cat in
        // case of it being down.
        const httpCat = await step.do("get cutest cat from KV", async () => {
            return await this.env.KV.get("cutest-http-cat");
        });

const image = await step.do("fetch cat image from http.cat", async () => {
            return await fetch(`https://http.cat/${httpCat}`);
        });
    }
}

index.tsts

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
        // ✅ Good: Unrelated API/Binding calls are self-contained, so that in case one of them fails
        // it can retry them individually. It also has an extra advantage: you can control retry or
        // timeout policies for each granular step - you might not to want to overload http.cat in
        // case of it being down.
        const httpCat = await step.do("get cutest cat from KV", async () => {
            return await this.env.KV.get("cutest-http-cat");
        });

const image = await step.do("fetch cat image from http.cat", async () => {
            return await fetch(`https://http.cat/${httpCat}`);
        });
    }
}

Otherwise, your entire Workflow might not be as durable as you might think, and you may encounter some undefined behaviour. You can avoid them by following the rules below:

🔴 Do not encapsulate your entire logic in one single step.
🔴 Do not call separate services in the same step (unless you need it to prove idempotency).
🔴 Do not make too many service calls in the same step (unless you need it to prove idempotency).
🔴 Do not do too much CPU-intensive work inside a single step - sometimes the engine may have to restart, and it will start over from the beginning of that step.
🔴 Avoid nested steps, particularly step.sleep() or step.waitForEvent() within a step.do().

index.jsjs

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event, step) {
        // 🔴 Bad: you are calling two separate services from within the same step. This might cause
        // some extra calls to the first service in case the second one fails, and in some cases, makes
        // the step non-idempotent altogether
        const image = await step.do("get cutest cat from KV", async () => {
            const httpCat = await this.env.KV.get("cutest-http-cat");
            return fetch(`https://http.cat/${httpCat}`);
        });
    }
}

index.tsts

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
        // 🔴 Bad: you are calling two separate services from within the same step. This might cause
        // some extra calls to the first service in case the second one fails, and in some cases, makes
        // the step non-idempotent altogether
        const image = await step.do("get cutest cat from KV", async () => {
            const httpCat = await this.env.KV.get("cutest-http-cat");
            return fetch(`https://http.cat/${httpCat}`);
        });
    }
}

Do not rely on state outside of a step

Workflows may hibernate and lose all in-memory state. This will happen when engine detects that there is no pending work and can hibernate until it needs to wake-up (because of a sleep, retry, or event).

This means that you should not store state outside of a step:

index.jsjs

function getRandomInt(min, max) {
    const minCeiled = Math.ceil(min);
    const maxFloored = Math.floor(max);
    return Math.floor(Math.random() * (maxFloored - minCeiled) + minCeiled); // The maximum is exclusive and the minimum is inclusive
}

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event, step) {
        // 🔴 Bad: `imageList` will be not persisted across engine's lifetimes. Which means that after hibernation,
        // `imageList` will be empty again, even though the following two steps have already ran.
        const imageList = [];

await step.do("get first cutest cat from KV", async () => {
            const httpCat = await this.env.KV.get("cutest-http-cat-1");

imageList.push(httpCat);
        });

await step.do("get second cutest cat from KV", async () => {
            const httpCat = await this.env.KV.get("cutest-http-cat-2");

imageList.push(httpCat);
        });

// A long sleep can (and probably will) hibernate the engine which means that the first engine lifetime ends here
        await step.sleep("💤💤💤💤", "3 hours");

// When this runs, it will be on the second engine lifetime - which means `imageList` will be empty.
        await step.do(
            "choose a random cat from the list and download it",
            async () => {
                const randomCat = imageList.at(getRandomInt(0, imageList.length));
                // this will fail since `randomCat` is undefined because `imageList` is empty
                return await fetch(`https://http.cat/${randomCat}`);
            },
        );
    }
}

index.tsts

function getRandomInt(min, max) {
    const minCeiled = Math.ceil(min);
    const maxFloored = Math.floor(max);
    return Math.floor(Math.random() * (maxFloored - minCeiled) + minCeiled); // The maximum is exclusive and the minimum is inclusive
}

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
        // 🔴 Bad: `imageList` will be not persisted across engine's lifetimes. Which means that after hibernation,
        // `imageList` will be empty again, even though the following two steps have already ran.
        const imageList: string[] = [];

await step.do("get first cutest cat from KV", async () => {
            const httpCat = await this.env.KV.get("cutest-http-cat-1");

imageList.push(httpCat);
        });

await step.do("get second cutest cat from KV", async () => {
            const httpCat = await this.env.KV.get("cutest-http-cat-2");

imageList.push(httpCat);
        });

// A long sleep can (and probably will) hibernate the engine which means that the first engine lifetime ends here
        await step.sleep("💤💤💤💤", "3 hours");

// When this runs, it will be on the second engine lifetime - which means `imageList` will be empty.
        await step.do(
            "choose a random cat from the list and download it",
            async () => {
                const randomCat = imageList.at(getRandomInt(0, imageList.length));
                // this will fail since `randomCat` is undefined because `imageList` is empty
                return await fetch(`https://http.cat/${randomCat}`);
            },
        );
    }
}

Instead, you should build top-level state exclusively comprised of step.do returns:

index.jsjs

function getRandomInt(min, max) {
    const minCeiled = Math.ceil(min);
    const maxFloored = Math.floor(max);
    return Math.floor(Math.random() * (maxFloored - minCeiled) + minCeiled); // The maximum is exclusive and the minimum is inclusive
}

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event, step) {
        // ✅ Good: imageList state is exclusively comprised of step returns - this means that in the event of
        // multiple engine lifetimes, imageList will be built accordingly
        const imageList = await Promise.all([
            step.do("get first cutest cat from KV", async () => {
                return await this.env.KV.get("cutest-http-cat-1");
            }),

step.do("get second cutest cat from KV", async () => {
                return await this.env.KV.get("cutest-http-cat-2");
            }),
        ]);

// A long sleep can (and probably will) hibernate the engine which means that the first engine lifetime ends here
        await step.sleep("💤💤💤💤", "3 hours");

// When this runs, it will be on the second engine lifetime - but this time, imageList will contain
        // the two most cutest cats
        await step.do(
            "choose a random cat from the list and download it",
            async () => {
                const randomCat = imageList.at(getRandomInt(0, imageList.length));
                // this will eventually succeed since `randomCat` is defined
                return await fetch(`https://http.cat/${randomCat}`);
            },
        );
    }
}

index.tsts

function getRandomInt(min, max) {
    const minCeiled = Math.ceil(min);
    const maxFloored = Math.floor(max);
    return Math.floor(Math.random() * (maxFloored - minCeiled) + minCeiled); // The maximum is exclusive and the minimum is inclusive
}

export class MyWorkflow extends WorkflowEntrypoint {
    async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
        // ✅ Good: imageList state is exclusively comprised of step returns - this means that in the event of
        // multiple engine lifetimes, imageList will be built accordingly
        const imageList: string[] = await Promise.all([
            step.do("get first cutest cat from KV", async () => {
                return await this.env.KV.get("cutest-http-cat-1");
            }),

step.do("get second cutest cat from KV", async () => {
                return await this.env.KV.get("cutest-http-cat-2");
            }),
        ]);

// A long sleep can (and probably will) hibernate the engine which means that the first engine lifetime ends here
        await step.sleep("💤💤💤💤", "3 hours");

// When this runs, it will be on the second engine lifetime - but this time, imageList will contain
        // the two most cutest cats
        await step.do(
            "choose a random cat from the list and download it",
            async () => {
                const randomCat = imageList.at(getRandomInt(0, imageList.length));
                // this will eventually succeed since `randomCat` is defined
                return await fetch(`https://http.cat/${randomCat}`);
            },
        );
    }
}

Avoid doing side effects outside of a `step.do`

It is not recommended to write code with any side effects outside of steps, unless you would like it to be repeated, because the Workflow engine may restart while an instance is running. If the engine restarts, the step logic will be preserved, but logic outside of the steps may be duplicated.

For example, a console.log() outside of workflow steps may cause the logs to print twice when the engine restarts.

However, logic involving non-serializable resources, like a database connection, should be executed outside of steps. Operations outside of a step.do might be repeated more than once, due to the nature of the Workflows' instance lifecycle.

Note

If you use Hyperdrive in a Workflow, create a new connection inside each step.do() and run your queries in that same step. Do not reuse a Hyperdrive-backed connection across steps.

index.jsjs

```js export class MyWorkflow extends WorkflowEntrypoint { async run(event, step) { // 🔴 Bad: creating instances outside of steps // This might get called more than once creating more instances than expected const badInstance = await this.env.ANOTHER_WORKFLOW.create();

Rules of Workflows

Rules of Workflows

Ensure API/Binding calls are idempotent

Make your steps granular

Do not rely on state outside of a step

Avoid doing side effects outside of a step.do

Avoid doing side effects outside of a `step.do`