/cloudflare-workflows

name: cloudflare-workflows
description: "Cloudflare Workflows for durable long-running execution. Use for multi-step workflows, retries, state persistence, or encountering NonRetryableError, execution failed errors."
license: MIT
metadata:
  version: "3.0.0"
  wrangler_version: "4.81.0"
  workers_types_version: "4.20260408.0"
  last_verified: "2025-12-27"
  errors_prevented: 5
  templates_included: 8
  references_included: 8
  agents_included: 3
  commands_included: 4
  scripts_included: 5
  keywords:
    - cloudflare workflows
    - workflows workers
    - durable execution
    - workflow step
    - WorkflowEntrypoint
    - step.do
    - step.sleep
    - workflow retries
    - NonRetryableError
    - workflow state
    - wrangler workflows
    - workflow events
    - long-running tasks
    - step.sleepUntil
    - step.waitForEvent
    - workflow bindings

Cloudflare Workflows

**Status**: Production Ready ✅ | **Last Verified**: 2025-12-27 | **Version**: 3.0.0

**Dependencies**: cloudflare-worker-base (for Worker setup)

**Contents**: [Quick Start](#quick-start-10-minutes) • [Commands](#commands) • [Agents](#agents) • [Core Concepts](#core-concepts) • [Critical Rules](#critical-rules) • [Top Errors](#top-5-errors-critical) • [Common Patterns](#common-patterns) • [When to Load References](#when-to-load-references) • [Limits](#limits--pricing)

---

Quick Start (10 Minutes)

1. Create a Workflow

Use the Cloudflare Workflows starter template:

npm create cloudflare@latest my-workflow -- --template cloudflare/workflows-starter --git --deploy false
cd my-workflow

**What you get:**

• WorkflowEntrypoint class template
• Worker to trigger workflows
• Complete wrangler.jsonc configuration

2. Basic Workflow Structure

**src/index.ts:**

import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

type Env = {
  MY_WORKFLOW: Workflow;
};

type Params = {
  userId: string;
  email: string;
};

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const { userId, email } = event.payload;

    // Step 1: Do work with automatic retries
    const result = await step.do('process user', async () => {
      return { processed: true, userId };
    });

    // Step 2: Wait before next step
    await step.sleep('wait 1 hour', '1 hour');

    // Step 3: Continue workflow
    await step.do('send email', async () => {
      return { sent: true, email };
    });

    return { completed: true, userId };
  }
}

// Worker to trigger workflow
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const instance = await env.MY_WORKFLOW.create({
      params: { userId: '123', email: 'user@example.com' }
    });

    return Response.json({
      id: instance.id,
      status: await instance.status()
    });
  }
};

**Template**: See `templates/basic-workflow.ts` for complete example

3. Configure wrangler.jsonc

{
  "name": "my-workflow",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-22",
  "workflows": [
    {
      "binding": "MY_WORKFLOW",
      "name": "my-workflow",
      "class_name": "MyWorkflow"
    }
  ]
}

**Template**: See `templates/wrangler-workflows-config.jsonc`

4. Deploy

npm run deploy

---

Commands

Interactive slash commands for workflow development:

| Command | Description | Use When | |---------|-------------|----------| | `/workflow-setup` | Complete wizard for new workflow projects | Starting new project, need full setup | | `/workflow-create` | Quick scaffolding for workflow classes | Adding workflow to existing project | | `/workflow-debug` | Interactive debugging with error patterns | Troubleshooting workflow issues | | `/workflow-test` | Test workflows locally and remotely | Validating workflow behavior |

**Example Usage**:

/workflow-setup   # Full guided setup wizard
/workflow-create  # Quick workflow scaffolding
/workflow-debug   # Debug workflow issues
/workflow-test    # Test workflow execution

---

Agents

Autonomous agents for complex workflow tasks:

| Agent | Description | Triggers | |-------|-------------|----------| | `workflow-debugger` | Auto-detects and fixes configuration/runtime errors | "debug workflow", "fix workflow errors" | | `workflow-optimizer` | Analyzes performance, cost, and reliability | "optimize workflow", "improve performance" | | `workflow-setup-assistant` | Autonomous project scaffolding | "setup workflow", "create first workflow" |

**Key Capabilities**:

• **Debugger**: 6-phase analysis, auto-fix for I/O context, serialization, export issues
• **Optimizer**: Cost analysis, reliability scoring, actionable recommendations
• **Setup Assistant**: Project detection, automatic scaffolding, validation

---

Scripts

Automation scripts in `scripts/` directory:

| Script | Purpose | |--------|---------| | `validate-workflow-config.sh` | Validate wrangler.jsonc configuration | | `test-workflow.sh` | Create and test workflow instances | | `benchmark-workflow.sh` | Measure performance and cost | | `generate-workflow.sh` | Scaffold new workflows from templates | | `check-workflow-limits.sh` | Validate against Cloudflare limits |

**Usage**:

./scripts/validate-workflow-config.sh           # Check config
./scripts/test-workflow.sh my-workflow          # Test workflow
./scripts/benchmark-workflow.sh my-workflow 10  # Benchmark 10 runs
./scripts/generate-workflow.sh MyWorkflow       # Generate scaffold
./scripts/check-workflow-limits.sh src/workflows/my-workflow.ts

---

Core Concepts

WorkflowEntrypoint

Every workflow must extend `WorkflowEntrypoint`:

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Workflow logic here
  }
}

**Key Points**:

• `Env`: Environment bindings (KV, D1, etc.)
• `Params`: Typed pa