Cloudflare Workflows

Cloudflare Workflows

Status: Production Ready ✅ Last Updated: 2025-10-22 Dependencies: cloudflare-worker-base (for Worker setup) Latest Versions: wrangler@4.44.0, @cloudflare/workers-types@4.20251014.0

---

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. Understand the Basic 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) {
    // Access params from event.payload
    const { userId, email } = event.payload;

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

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

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

    // Optional: return final state
    return { completed: true, userId };
  }
}

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

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

3. Configure Wrangler

wrangler.jsonc:

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

4. Deploy and Test

# Deploy workflow
npm run deploy

# Trigger workflow (visit in browser or curl)
curl https://my-workflow.<subdomain>.workers.dev/

# View workflow instances
npx wrangler workflows instances list my-workflow

# Check instance status
npx wrangler workflows instances describe my-workflow <instance-id>

---

WorkflowEntrypoint Class

Extend WorkflowEntrypoint

Every Workflow must extend WorkflowEntrypoint and implement a run() method:

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

Type Parameters:

• Env - Environment bindings (KV, D1, R2, etc.)
• Params - Type of workflow parameters passed via event.payload

run() Method

async run(
  event: WorkflowEvent<Params>,
  step: WorkflowStep
): Promise<T | void>

Parameters:

• event - Contains workflow metadata and payload
• step - Provides step methods (do, sleep, sleepUntil, waitForEvent)

Returns:

• Optional return value (must be serializable)
• Return value available via instance.status()

Example:

export class OrderWorkflow extends WorkflowEntrypoint<Env, OrderParams> {
  async run(event: WorkflowEvent<OrderParams>, step: WorkflowStep) {
    const { orderId, customerId } = event.payload;

    // Access bindings via this.env
    const order = await this.env.DB.prepare(
      'SELECT * FROM orders WHERE id = ?'
    ).bind(orderId).first();

    const result = await step.do('process payment', async () => {
      // Payment processing
      return { paid: true, amount: order.total };
    });

    // Return final state
    return {
      orderId,
      status: 'completed',
      paidAmount: result.amount
    };
  }
}

---

Step Methods

step.do() - Execute Work

step.do<T>(
  name: string,
  config?: WorkflowStepConfig,
  callback: () => Promise<T>
): Promise<T>

OR (config is optional):

step.do<T>(
  name: string,
  callback: () => Promise<T>
): Promise<T>

Parameters:

• name - Step name (for observability)
• config (optional) - Retry configuration
• callback - Async function that does the work

Returns:

• The value returned from callback (must be serializable)

Example:

// Simple step
const files = await step.do('fetch files', async () => {
  const response = await fetch('https://api.example.com/files');
  return await response.json();
});

// Step with retry config
const result = await step.do(
  'call payment API',
  {
    retries: {
      limit: 10,
      delay: '10 seconds',
      backoff: 'exponential'
    },
    timeout: '5 minutes'
  },
  async () => {
    const response = await fetch('https://payment-api.example.com/charge', {
      method: 'POST',
      body: JSON.stringify({ amount: 100 })
    });
    return await response.json();
  }
);

CRITICAL - Serialization:

• Return value must be JSON serializable
• ✅ Allowed: string, number, boolean, Array, Object, null
• ❌ Forbidden: Function, Symbol, circular references, undefined
• Step will throw error if return value isn't serializable

---

step.sleep() - Relative Sleep

step.sleep(name: string, duration: WorkflowDuration): Promise<void>

Parameters:

• name - Step name
• duration - Number (milliseconds) or human-readable string

Accepted units:

• "second" / "seconds"
• "minute" / "minutes"
• "hour" / "hours"
• "day" / "days"
• "week" / "weeks"
• "month" / "months"
• "year" / "years"

Examples:

// Sleep for 5 minutes
await step.sleep('wait 5 minutes', '5 minutes');

// Sleep for 1 hour
await step.sleep('hourly delay', '1 hour');

// Sleep for 2 days
await step.sleep('wait 2 days', '2 days');

// Sleep using milliseconds
await step.sleep('wait 30 seconds', 30000);

// Common pattern: schedule daily task
await step.do('send daily report', async () => {
  // Send report
});
await step.sleep('wait until tomorrow', '1 day');
// Workflow continues next day

Priority:

• Workflows resuming from sleep take priority over new instances
• Ensures older workflows complete before new ones start

---

step.sleepUntil() - Sleep to Specific Date

step.sleepUntil(
  name: string,
  timestamp: Date | number
): Promise<void>

Parameters:

• name - Step name
• timestamp - Date object or UNIX timestamp (milliseconds)

Examples:

// Sleep until specific date
const launchDate = new Date('2025-12-25T00:00:00Z');
await step.sleepUntil('wait for launch', launchDate);

// Sleep until UNIX timestamp
const timestamp = Date.parse('24 Oct 2024 13:00:00 UTC');
await step.sleepUntil('wait until time', timestamp);

// Sleep until next Monday 9am UTC
const nextMonday = new Date();
nextMonday.setDate(nextMonday.getDate() + ((1 + 7 - nextMonday.getDay()) % 7 || 7));
nextMonday.setUTCHours(9, 0, 0, 0);
await step.sleepUntil('wait until Monday 9am', nextMonday);

// Schedule work at specific time
await step.do('prepare campaign', async () => {
  // Prepare marketing campaign
});

const campaignLaunch = new Date('2025-11-01T12:00:00Z');
await step.sleepUntil('wait for campaign launch', campaignLaunch);

await step.do('launch campaign', async () => {
  // Launch campaign
});

---

step.waitForEvent() - Wait for External Event

step.waitForEvent<T>(
  name: string,
  options: { type: string; timeout?: string | number }
): Promise<T>

Parameters:

• name - Step name
• options.type - Event type to match
• options.timeout (optional) - Max wait time (default: 24 hours)

Returns:

• The event payload sent via instance.sendEvent()

Example:

export class PaymentWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Create payment intent
    await step.do('create payment intent', async () => {
      // Call Stripe API
    });

    // Wait for webhook from Stripe (max 1 hour)
    const webhookData = await step.waitForEvent<StripeWebhook>(
      'wait for payment confirmation',
      { type: 'stripe-webhook', timeout: '1 hour' }
    );

    // Continue based on webhook
    if (webhookData.status === 'succeeded') {
      await step.do('fulfill order', async () => {
        // Fulfill order
      });
    } else {
      await step.do('handle failed payment', async () => {
        // Handle failure
      });
    }
  }
}

// Worker receives webhook and sends event to workflow
export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    if (req.url.includes('/webhook/stripe')) {
      const webhookData = await req.json();

      // Get workflow instance by ID (stored when created)
      const instance = await env.PAYMENT_WORKFLOW.get(instanceId);

      // Send event to waiting workflow
      await instance.sendEvent({
        type: 'stripe-webhook',
        payload: webhookData
      });

      return new Response('OK');
    }
  }
};

Timeout behavior:

• If timeout expires, throws error and workflow can retry or fail
• Wrap in try-catch if timeout should not fail workflow

try {
  const event = await step.waitForEvent('wait for user input', {
    type: 'user-submitted',
    timeout: '10 minutes'
  });
} catch (error) {
  // Timeout occurred - handle gracefully
  await step.do('send reminder', async () => {
    // Send reminder to user
  });
}

---

WorkflowStepConfig

Configure retry behavior for individual steps:

interface WorkflowStepConfig {
  retries?: {
    limit: number;          // Max retry attempts (Infinity allowed)
    delay: string | number; // Delay between retries
    backoff?: 'constant' | 'linear' | 'exponential';
  };
  timeout?: string | number; // Max time per attempt
}

Default Configuration

If no config provided, Workflows uses:

{
  retries: {
    limit: 5,
    delay: 10000,      // 10 seconds
    backoff: 'exponential'
  },
  timeout: '10 minutes'
}

Retry Examples

Constant Backoff (same delay each time):

await step.do(
  'send email',
  {
    retries: {
      limit: 3,
      delay: '30 seconds',
      backoff: 'constant'  // Always wait 30 seconds
    }
  },
  async () => {
    // Send email
  }
);

Linear Backoff (increasing delay):

await step.do(
  'poll API',
  {
    retries: {
      limit: 5,
      delay: '1 minute',
      backoff: 'linear'  // 1m, 2m, 3m, 4m, 5m
    }
  },
  async () => {
    // Poll API
  }
);

Exponential Backoff (recommended for most cases):

await step.do(
  'call rate-limited API',
  {
    retries: {
      limit: 10,
      delay: '10 seconds',
      backoff: 'exponential'  // 10s, 20s, 40s, 80s, 160s, ...
    },
    timeout: '5 minutes'
  },
  async () => {
    // API call
  }
);

Unlimited Retries:

await step.do(
  'critical operation',
  {
    retries: {
      limit: Infinity,  // Retry forever
      delay: '1 minute',
      backoff: 'exponential'
    }
  },
  async () => {
    // Operation that must succeed eventually
  }
);

No Retries:

await step.do(
  'non-idempotent operation',
  {
    retries: {
      limit: 0  // Fail immediately on error
    }
  },
  async () => {
    // One-time operation
  }
);

---

Error Handling

NonRetryableError

Force workflow to fail immediately without retrying:

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

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    await step.do('validate input', async () => {
      if (!event.payload.userId) {
        throw new NonRetryableError('userId is required');
      }

      // Validate user exists
      const user = await this.env.DB.prepare(
        'SELECT * FROM users WHERE id = ?'
      ).bind(event.payload.userId).first();

      if (!user) {
        // Terminal error - retrying won't help
        throw new NonRetryableError('User not found');
      }

      return user;
    });
  }
}

When to use NonRetryableError:

• ✅ Authentication/authorization failures
• ✅ Invalid input that won't change
• ✅ Resource doesn't exist (404)
• ✅ Validation errors
• ❌ Network failures (should retry)
• ❌ Rate limits (should retry with backoff)
• ❌ Temporary service outages (should retry)

---

Catch Errors to Continue Workflow

Prevent entire workflow from failing by catching step errors:

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Critical step - workflow fails if this fails
    await step.do('process payment', async () => {
      // Payment processing
    });

    // Optional step - workflow continues even if it fails
    try {
      await step.do('send confirmation email', async () => {
        // Email sending
      });
    } catch (error) {
      console.log(`Email failed: ${error.message}`);

      // Do cleanup or alternative action
      await step.do('log email failure', async () => {
        await this.env.DB.prepare(
          'INSERT INTO failed_emails (user_id, error) VALUES (?, ?)'
        ).bind(event.payload.userId, error.message).run();
      });
    }

    // Workflow continues
    await step.do('update order status', async () => {
      // Update status
    });
  }
}

Pattern: Graceful degradation:

// Try primary service, fall back to secondary
let result;

try {
  result = await step.do('call primary API', async () => {
    return await callPrimaryAPI();
  });
} catch (error) {
  console.log('Primary API failed, trying backup');

  result = await step.do('call backup API', async () => {
    return await callBackupAPI();
  });
}

---

Triggering Workflows

From Workers

Configure binding in wrangler.jsonc:

{
  "name": "trigger-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-10-22",
  "workflows": [
    {
      "name": "my-workflow",
      "binding": "MY_WORKFLOW",
      "class_name": "MyWorkflow",
      "script_name": "workflow-worker"  // If workflow is in different Worker
    }
  ]
}

Trigger from Worker:

type Env = {
  MY_WORKFLOW: Workflow;
};

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

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

Get Instance Status

// Get instance by ID
const instance = await env.MY_WORKFLOW.get(instanceId);

// Get status
const status = await instance.status();

console.log(status);
// {
//   status: 'running' | 'complete' | 'errored' | 'queued' | 'unknown',
//   error: string | null,
//   output: any  // Return value from run() if complete
// }

Send Events to Running Instance

// Get instance
const instance = await env.MY_WORKFLOW.get(instanceId);

// Send event (will be received by step.waitForEvent)
await instance.sendEvent({
  type: 'user-action',
  payload: { action: 'approved' }
});

Pause and Resume

// Pause instance
await instance.pause();

// Resume instance
await instance.resume();

// Terminate instance
await instance.terminate();

---

Workflow Patterns

Pattern 1: Long-Running Process

export class VideoProcessingWorkflow extends WorkflowEntrypoint<Env, VideoParams> {
  async run(event: WorkflowEvent<VideoParams>, step: WorkflowStep) {
    const { videoId } = event.payload;

    // Step 1: Upload to processing service
    const uploadResult = await step.do('upload video', async () => {
      const video = await this.env.MY_BUCKET.get(`videos/${videoId}`);
      const response = await fetch('https://processor.example.com/upload', {
        method: 'POST',
        body: video?.body
      });
      return await response.json();
    });

    // Step 2: Wait for processing (could take hours)
    await step.sleep('wait for initial processing', '10 minutes');

    // Step 3: Poll for completion
    let processed = false;
    let attempts = 0;

    while (!processed && attempts < 20) {
      const status = await step.do(`check status attempt ${attempts}`, async () => {
        const response = await fetch(
          `https://processor.example.com/status/${uploadResult.jobId}`
        );
        return await response.json();
      });

      if (status.complete) {
        processed = true;
      } else {
        attempts++;
        await step.sleep(`wait before retry ${attempts}`, '5 minutes');
      }
    }

    // Step 4: Download processed video
    await step.do('download processed video', async () => {
      const response = await fetch(uploadResult.downloadUrl);
      const processed = await response.blob();
      await this.env.MY_BUCKET.put(`processed/${videoId}`, processed);
    });

    return { videoId, status: 'complete' };
  }
}

---

Pattern 2: Event-Driven Approval Flow

export class ApprovalWorkflow extends WorkflowEntrypoint<Env, ApprovalParams> {
  async run(event: WorkflowEvent<ApprovalParams>, step: WorkflowStep) {
    const { requestId, requesterId } = event.payload;

    // Step 1: Create approval request
    await step.do('create approval request', async () => {
      await this.env.DB.prepare(
        'INSERT INTO approvals (id, requester_id, status) VALUES (?, ?, ?)'
      ).bind(requestId, requesterId, 'pending').run();
    });

    // Step 2: Send notification to approvers
    await step.do('notify approvers', async () => {
      await sendNotification(requestId);
    });

    // Step 3: Wait for approval (max 7 days)
    let approvalEvent;

    try {
      approvalEvent = await step.waitForEvent<ApprovalEvent>(
        'wait for approval decision',
        { type: 'approval-decision', timeout: '7 days' }
      );
    } catch (error) {
      // Timeout - auto-reject
      await step.do('auto-reject due to timeout', async () => {
        await this.env.DB.prepare(
          'UPDATE approvals SET status = ? WHERE id = ?'
        ).bind('rejected', requestId).run();
      });

      return { requestId, status: 'rejected', reason: 'timeout' };
    }

    // Step 4: Process decision
    await step.do('process approval decision', async () => {
      await this.env.DB.prepare(
        'UPDATE approvals SET status = ?, approver_id = ? WHERE id = ?'
      ).bind(approvalEvent.approved ? 'approved' : 'rejected', approvalEvent.approverId, requestId).run();
    });

    // Step 5: Execute approved action (if approved)
    if (approvalEvent.approved) {
      await step.do('execute approved action', async () => {
        // Execute the action
      });
    }

    return { requestId, status: approvalEvent.approved ? 'approved' : 'rejected' };
  }
}

---

Pattern 3: Scheduled Workflow

export class DailyReportWorkflow extends WorkflowEntrypoint<Env, ReportParams> {
  async run(event: WorkflowEvent<ReportParams>, step: WorkflowStep) {
    // Calculate next 9am UTC
    const now = new Date();
    const tomorrow9am = new Date();
    tomorrow9am.setUTCDate(tomorrow9am.getUTCDate() + 1);
    tomorrow9am.setUTCHours(9, 0, 0, 0);

    // Sleep until tomorrow 9am
    await step.sleepUntil('wait until 9am tomorrow', tomorrow9am);

    // Generate report
    const report = await step.do('generate daily report', async () => {
      const results = await this.env.DB.prepare(
        'SELECT * FROM metrics WHERE date = ?'
      ).bind(now.toISOString().split('T')[0]).all();

      return {
        date: now.toISOString().split('T')[0],
        metrics: results.results
      };
    });

    // Send report
    await step.do('send report', async () => {
      await sendEmail({
        to: event.payload.recipients,
        subject: `Daily Report - ${report.date}`,
        body: formatReport(report.metrics)
      });
    });

    return { sent: true, date: report.date };
  }
}

---

Pattern 4: Workflow Chaining

export class OrderWorkflow extends WorkflowEntrypoint<Env, OrderParams> {
  async run(event: WorkflowEvent<OrderParams>, step: WorkflowStep) {
    const { orderId } = event.payload;

    // Step 1: Process payment
    const paymentResult = await step.do('process payment', async () => {
      return await processPayment(orderId);
    });

    // Step 2: Trigger fulfillment workflow
    const fulfillmentInstance = await step.do('start fulfillment', async () => {
      return await this.env.FULFILLMENT_WORKFLOW.create({
        params: {
          orderId,
          paymentId: paymentResult.id
        }
      });
    });

    // Step 3: Wait for fulfillment to complete
    await step.sleep('wait for fulfillment', '5 minutes');

    // Step 4: Check fulfillment status
    const fulfillmentStatus = await step.do('check fulfillment', async () => {
      const instance = await this.env.FULFILLMENT_WORKFLOW.get(fulfillmentInstance.id);
      return await instance.status();
    });

    if (fulfillmentStatus.status === 'complete') {
      // Step 5: Send confirmation
      await step.do('send order confirmation', async () => {
        await sendConfirmation(orderId);
      });
    }

    return { orderId, status: 'complete' };
  }
}

---

Wrangler Commands

List Workflow Instances

# List all instances of a workflow
npx wrangler workflows instances list my-workflow

# Filter by status
npx wrangler workflows instances list my-workflow --status running
npx wrangler workflows instances list my-workflow --status complete
npx wrangler workflows instances list my-workflow --status errored

Describe Instance

# Get detailed info about specific instance
npx wrangler workflows instances describe my-workflow <instance-id>

# Output shows:
# - Current status (running/complete/errored)
# - Each step with start/end times
# - Step outputs
# - Retry history
# - Any errors
# - Sleep state (if sleeping)

Trigger Workflow (Development)

# Deploy workflow
npx wrangler deploy

# Trigger via HTTP (if Worker is set up to trigger)
curl https://my-workflow.<subdomain>.workers.dev/

---

State Persistence

What Can Be Persisted

Workflows automatically persist state returned from step.do():

✅ Serializable Types:

• Primitives: string, number, boolean, null
• Arrays: [1, 2, 3], ['a', 'b', 'c']
• Objects: { key: 'value' }, { nested: { data: true } }
• Nested structures: { users: [{ id: 1, name: 'Alice' }] }

❌ Non-Serializable Types:

• Functions: () => {}
• Symbols: Symbol('key')
• Circular references: const obj = {}; obj.self = obj;
• undefined (use null instead)
• Class instances (serialize to plain objects)

Example - Correct Serialization:

// ✅ Good - all values serializable
const result = await step.do('fetch data', async () => {
  return {
    users: [
      { id: 1, name: 'Alice', active: true },
      { id: 2, name: 'Bob', active: false }
    ],
    timestamp: Date.now(),
    metadata: null
  };
});

// ❌ Bad - contains function
const bad = await step.do('bad example', async () => {
  return {
    data: [1, 2, 3],
    transform: (x) => x * 2  // ❌ Function not serializable
  };
});
// This will throw an error!

Access State Across Steps

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Step 1: Get data
    const userData = await step.do('fetch user', async () => {
      return { id: 123, email: 'user@example.com' };
    });

    // Step 2: Use data from step 1
    const orderData = await step.do('create order', async () => {
      return {
        userId: userData.id,      // ✅ Access previous step's data
        userEmail: userData.email,
        orderId: 'ORD-456'
      };
    });

    // Step 3: Use data from step 1 and 2
    await step.do('send confirmation', async () => {
      await sendEmail({
        to: userData.email,       // ✅ Still accessible
        subject: `Order ${orderData.orderId} confirmed`
      });
    });
  }
}

---

Observability

Built-in Metrics

Workflows automatically track:

• Instance status: queued, running, complete, errored, paused
• Step execution: start/end times, duration, success/failure
• Retry history: attempts, errors, delays
• Sleep state: when workflow will wake up
• Output: return values from steps and run()

View Metrics in Dashboard

Access via Cloudflare dashboard: 1. Workers & Pages 2. Select your workflow 3. View instances and metrics

Metrics include:

• Total instances created
• Success/error rates
• Average execution time
• Step-level performance

Programmatic Access

// Get instance status
const instance = await env.MY_WORKFLOW.get(instanceId);
const status = await instance.status();

console.log(status);
// {
//   status: 'complete',
//   error: null,
//   output: { userId: '123', status: 'processed' }
// }

---

Limits

Notes:

• step.sleep() and step.sleepUntil() do NOT count toward 10,000 step limit
• Workflows can run for up to 30 days total
• Each step execution limited to 15 minutes max
• Retries count as separate attempts, not separate steps

---

Pricing

Requires Workers Paid plan ($5/month)

Workflow Executions:

• First 10,000,000 step executions/month: FREE
• After that: $0.30 per million step executions

What counts as a step execution:

• Each step.do() call
• Each retry of a step
• step.sleep(), step.sleepUntil(), step.waitForEvent() do NOT count

Cost examples:

• Workflow with 5 steps, no retries: 5 step executions
• Workflow with 3 steps, 1 step retries 2 times: 5 step executions (3 + 2)
• 10M simple workflows/month (5 steps each): ((50M - 10M) / 1M) × $0.30 = $12/month

---

Always Do ✅

1. Use descriptive step names - "fetch user data", not "step 1" 2. Return serializable values only - primitives, arrays, plain objects 3. Use NonRetryableError for terminal errors - auth failures, invalid input 4. Configure retry limits - avoid infinite retries unless necessary 5. Catch errors for optional steps - use try-catch if step can fail gracefully 6. Use exponential backoff for retries - default backoff for most cases 7. Validate inputs early - fail fast with NonRetryableError if invalid 8. Store workflow instance IDs - save to DB/KV to query status later 9. Use waitForEvent for human-in-loop - approvals, external confirmations 10. Monitor workflow metrics - track success rates and errors

---

Never Do ❌

1. Never return functions from steps - will throw serialization error 2. Never create circular references - will fail to serialize 3. Never assume steps execute immediately - they may retry or sleep 4. Never use blocking operations - use step.do() for async work 5. Never exceed 128 KB payload/output - will fail 6. Never retry non-idempotent operations infinitely - use retry limits 7. Never ignore serialization errors - fix the data structure 8. Never use workflows for real-time operations - use Durable Objects instead 9. Never skip error handling for critical steps - wrap in try-catch or use NonRetryableError 10. Never assume step order is guaranteed across retries - each step is independent

---

Troubleshooting

Issue: "Cannot perform I/O on behalf of a different request"

Cause: Trying to use I/O objects created in one request context from another request handler

Solution: Always perform I/O within step.do() callbacks

// ❌ Bad - I/O outside step
const response = await fetch('https://api.example.com/data');
const data = await response.json();

await step.do('use data', async () => {
  // Using data from outside step's I/O context
  return data;  // This will fail!
});

// ✅ Good - I/O inside step
const data = await step.do('fetch data', async () => {
  const response = await fetch('https://api.example.com/data');
  return await response.json();  // ✅ Correct
});

---

Issue: NonRetryableError behaves differently in dev vs production

Known Issue: Throwing NonRetryableError with empty message in dev mode causes retries, but works correctly in production

Workaround: Always provide a message to NonRetryableError

// ❌ May retry in dev
throw new NonRetryableError();

// ✅ Works consistently
throw new NonRetryableError('User not found');

Source: workers-sdk#10113

---

Issue: "The requested module 'cloudflare:workers' does not provide an export named 'WorkflowEvent'"

Cause: Incorrect import or outdated @cloudflare/workers-types

Solution:

# Update types
npm install -D @cloudflare/workers-types@latest

# Ensure correct import
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';
import { NonRetryableError } from 'cloudflare:workflows';

---

Issue: Step returns undefined instead of expected value

Cause: Step callback doesn't return a value

Solution: Always return from step callbacks

// ❌ Bad - no return
const result = await step.do('get data', async () => {
  const data = await fetchData();
  // Missing return!
});
console.log(result);  // undefined

// ✅ Good - explicit return
const result = await step.do('get data', async () => {
  const data = await fetchData();
  return data;  // ✅
});

---

Issue: Workflow instance stuck in "running" state

Possible causes: 1. Step is sleeping for long duration 2. Step is waiting for event that never arrives 3. Step is retrying with long backoff

Solution:

# Check instance details
npx wrangler workflows instances describe my-workflow <instance-id>

# Look for:
# - Sleep state (will show wake time)
# - Waiting for event (will show event type and timeout)
# - Retry history (will show attempts and delays)

---

Production Checklist

Before deploying workflows to production:

• [ ] All steps have descriptive names
• [ ] Retry limits configured for all steps
• [ ] NonRetryableError used for terminal errors
• [ ] Critical steps have error handling
• [ ] Optional steps wrapped in try-catch
• [ ] No non-serializable values returned
• [ ] Payload sizes under 128 KB
• [ ] Workflow duration under 30 days
• [ ] Instance IDs stored for status queries
• [ ] Monitoring and alerting configured
• [ ] waitForEvent timeouts configured
• [ ] Tested in development environment
• [ ] Tested retry behavior
• [ ] Tested error scenarios

---

Related Documentation

• Cloudflare Workflows Docs
• Get Started Guide
• Workers API
• Sleeping and Retrying
• Events and Parameters
• Limits
• Pricing
• Changelog

---

Last Updated: 2025-10-22 Version: 1.0.0 Maintainer: Jeremy Dawes | jeremy@jezweb.net

Cloudflare Workflows Skill

Status: Production Ready ✅ Last Updated: 2025-10-22 Production Tested: Yes

---

Auto-Trigger Keywords

Primary Keywords:

• Cloudflare Workflows
• workflows
• durable execution
• WorkflowEntrypoint
• workflow step
• long-running tasks
• multi-step applications

Secondary Keywords:

• step.do
• step.sleep
• step.sleepUntil
• step.waitForEvent
• workflow retries
• workflow state
• NonRetryableError
• workflow events
• workflow bindings
• wrangler workflows

Error-Based Keywords:

• NonRetryableError
• I/O context error
• workflow execution failed
• serialization error
• WorkflowEvent not found
• Cannot perform I/O on behalf of a different request
• workflow stuck running
• payload too large

Framework Keywords:

• Cloudflare Workers
• wrangler
• @cloudflare/workers-types
• cloudflare:workers
• cloudflare:workflows

---

What This Skill Does

This skill provides complete, production-ready knowledge for Cloudflare Workflows - a durable execution framework for building multi-step applications on Workers that:

• Automatically retry failed steps with configurable backoff
• Persist state between steps so workflows survive failures
• Run for hours or days with built-in sleep and scheduling
• Wait for external events to enable human-in-the-loop patterns
• Coordinate between APIs with reliable execution guarantees

Use this skill when:

• Building long-running processes (hours/days)
• Implementing retry logic for reliability
• Creating event-driven workflows
• Scheduling multi-step tasks
• Coordinating between third-party APIs
• Building approval/review workflows
• Processing data pipelines
• Handling webhook orchestration

---

Known Issues Prevented

This skill prevents 5 documented errors with sources:

Error Prevention: 5/5 = 100%

---

Token Efficiency

Why the savings:

• Complete API reference (no searching docs)
• 6 working templates (copy-paste ready)
• All known issues documented with fixes
• Production patterns included
• Retry configuration examples

---

What's Included

SKILL.md (Comprehensive Guide)

• Quick Start (10 minutes to first workflow)
• Complete WorkflowEntrypoint API
• All step methods: do, sleep, sleepUntil, waitForEvent
• Retry configuration (limits, backoff, timeouts)
• Error handling (NonRetryableError, try-catch)
• Triggering workflows (from Workers, HTTP, scheduled)
• State persistence rules
• Wrangler commands
• Production checklist

Templates (6 Files)

1. basic-workflow.ts - Simple 3-step workflow with retries 2. workflow-with-retries.ts - Advanced retry config with exponential/linear/constant backoff 3. scheduled-workflow.ts - Daily/weekly/monthly scheduled workflows 4. workflow-with-events.ts - Event-driven approval flow with timeout 5. worker-trigger.ts - Worker that creates, queries, and manages workflows 6. wrangler-workflows-config.jsonc - Complete configuration example

References

1. common-issues.md - 5 documented errors with sources and solutions 2. workflow-patterns.md - Production patterns (idempotency, error handling, long-running, human-in-loop, chaining, testing, monitoring)

---

Quick Example

Create a workflow:

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

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    // Step 1: Do work (auto-retries on failure)
    const data = await step.do('fetch data', async () => {
      const response = await fetch('https://api.example.com/data');
      return await response.json();
    });

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

    // Step 3: Continue workflow
    await step.do('process data', async () => {
      // Process data
      return { processed: true };
    });

    return { status: 'complete' };
  }
}

Trigger from Worker:

const instance = await env.MY_WORKFLOW.create({
  params: { userId: '123' }
});

const status = await instance.status();

---

When to Use This Skill

✅ Use Workflows when:

• Process takes longer than 30 seconds (Workers timeout)
• Need automatic retries with backoff
• Need to sleep/schedule between steps
• Coordinating multiple async operations
• Waiting for external events (webhooks, approvals)
• Building reliable data pipelines
• Orchestrating microservices
• Processing batch jobs over time

❌ Don't use Workflows when:

• Need real-time responses (<100ms)
• Handling simple HTTP requests
• No retry logic needed
• All work completes in <10 seconds
• Need WebSocket connections (use Durable Objects)

---

Latest Versions (Verified 2025-10-22)

{
  "devDependencies": {
    "wrangler": "^4.44.0",
    "@cloudflare/workers-types": "^4.20251014.0",
    "typescript": "^5.9.0"
  }
}

---

Official Documentation

• Workflows Docs: https://developers.cloudflare.com/workflows/
• Get Started: https://developers.cloudflare.com/workflows/get-started/guide/
• Workers API: https://developers.cloudflare.com/workflows/build/workers-api/
• Sleeping & Retrying: https://developers.cloudflare.com/workflows/build/sleeping-and-retrying/
• Events & Parameters: https://developers.cloudflare.com/workflows/build/events-and-parameters/
• Limits: https://developers.cloudflare.com/workflows/reference/limits/
• Pricing: https://developers.cloudflare.com/workflows/platform/pricing/

---

Related Skills

• cloudflare-worker-base - Hono + Vite + Static Assets foundation
• cloudflare-queues - Message queues for async processing
• cloudflare-d1 - D1 serverless SQL database
• cloudflare-kv - KV key-value storage

---

Questions? Issues?

1. Check references/common-issues.md for known errors 2. Review references/workflow-patterns.md for production patterns 3. Use templates in templates/ directory 4. Consult official docs: https://developers.cloudflare.com/workflows/

---

Maintainer: Jeremy Dawes | jeremy@jezweb.net

Cloudflare Workflows - Common Issues

Last Updated: 2025-10-22

This document details all known issues with Cloudflare Workflows and their solutions.

---

Issue #1: I/O Context Error

Error Message:

Cannot perform I/O on behalf of a different request

Description: When trying to use I/O objects (like fetch responses, file handles, etc.) created in one request context from a different request's handler, Cloudflare Workers throws this error. This is a fundamental Workers platform limitation.

Root Cause: I/O objects are bound to the request context that created them. Workflows create a new execution context for each step, so I/O must happen within the step's callback.

Prevention:

❌ Bad - I/O outside step:

// This will fail!
const response = await fetch('https://api.example.com/data');
const data = await response.json();

await step.do('use data', async () => {
  // Trying to use data from outside step's context
  return data;  // ❌ Error!
});

✅ Good - I/O inside step:

const data = await step.do('fetch data', async () => {
  const response = await fetch('https://api.example.com/data');
  return await response.json();  // ✅ Correct
});

Workaround: Always perform all I/O operations (fetch, KV reads, D1 queries, R2 operations) within step.do() callbacks.

Source: Cloudflare Workers platform limitation

---

Issue #2: NonRetryableError Behaves Differently in Dev vs Production

Error Message:

(No specific error - workflow retries when it shouldn't)

Description: When throwing a NonRetryableError with an empty message in development mode (wrangler dev), the workflow incorrectly retries the failed step. In production, it correctly exits without retrying.

Root Cause: Bug in the development environment handling of empty NonRetryableError messages.

Prevention:

❌ Bad - Empty message:

import { NonRetryableError } from 'cloudflare:workflows';

// May retry in dev mode
throw new NonRetryableError();

✅ Good - Always provide message:

import { NonRetryableError } from 'cloudflare:workflows';

// Works consistently in dev and production
throw new NonRetryableError('User not found');
throw new NonRetryableError('Invalid authentication credentials');
throw new NonRetryableError('Amount exceeds limit');

Workaround: Always provide a descriptive message when throwing NonRetryableError.

Source: cloudflare/workers-sdk#10113 Status: Reported July 2025, not yet fixed

---

Issue #3: WorkflowEvent Export Not Found

Error Message:

The requested module 'cloudflare:workers' does not provide an export named 'WorkflowEvent'

Description: TypeScript cannot find the WorkflowEvent export from the cloudflare:workers module. This usually happens with outdated type definitions.

Root Cause:

• Outdated @cloudflare/workers-types package
• Incorrect import statement
• Missing types in tsconfig.json

Prevention:

✅ Ensure latest types installed:

npm install -D @cloudflare/workers-types@latest

✅ Correct import:

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

✅ Correct tsconfig.json:

{
  "compilerOptions": {
    "types": ["@cloudflare/workers-types/2023-07-01"],
    "moduleResolution": "bundler"
  }
}

Workaround: 1. Update workers types: npm install -D @cloudflare/workers-types@latest 2. Run type generation: npx wrangler types 3. Restart TypeScript server in your editor

Source: Community reports, package versioning issues Latest Working Version: @cloudflare/workers-types@4.20251014.0 (verified 2025-10-22)

---

Issue #4: Serialization Error - Non-Serializable Return Values

Error Message:

Error: Could not serialize return value
(or workflow hangs without clear error)

Description: Attempting to return non-serializable values from step.do() or run() methods causes serialization failures. The workflow instance may error or hang.

Root Cause: Workflows persist state between steps by serializing return values. Only JSON-serializable types are supported.

Prevention:

❌ Bad - Non-serializable types:

// ❌ Function
await step.do('bad example', async () => {
  return {
    data: [1, 2, 3],
    transform: (x) => x * 2  // ❌ Function not serializable
  };
});

// ❌ Circular reference
await step.do('bad example 2', async () => {
  const obj: any = { name: 'test' };
  obj.self = obj;  // ❌ Circular reference
  return obj;
});

// ❌ Symbol
await step.do('bad example 3', async () => {
  return {
    id: Symbol('unique'),  // ❌ Symbol not serializable
    data: 'test'
  };
});

// ❌ undefined (use null instead)
await step.do('bad example 4', async () => {
  return {
    value: undefined  // ❌ undefined not serializable
  };
});

✅ Good - Only serializable types:

await step.do('good example', async () => {
  return {
    // ✅ Primitives
    string: 'value',
    number: 123,
    boolean: true,
    nullValue: null,

    // ✅ Arrays
    array: [1, 2, 3],

    // ✅ Objects
    nested: {
      data: 'test',
      items: [{ id: 1 }, { id: 2 }]
    }
  };
});

✅ Convert class instances to plain objects:

class User {
  constructor(public id: string, public name: string) {}

  toJSON() {
    return { id: this.id, name: this.name };
  }
}

await step.do('serialize class', async () => {
  const user = new User('123', 'Alice');

  // ✅ Convert to plain object
  return user.toJSON();  // { id: '123', name: 'Alice' }
});

Workaround:

• Only return primitives, arrays, and plain objects
• Convert class instances to plain objects before returning
• Use null instead of undefined
• Avoid circular references

Source: Cloudflare Workflows documentation Reference: Workflows Workers API

---

Issue #5: Testing Workflows in CI Environments

Error Message:

(Tests pass locally but fail in CI)

Description: Tests that use vitest-pool-workers to test workflows work reliably in local development but fail inconsistently in CI environments (GitHub Actions, GitLab CI, etc.).

Root Cause:

• Timing issues in CI environments
• Resource constraints in CI runners
• Race conditions in test setup/teardown

Prevention:

✅ Increase timeouts in CI:

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    testTimeout: 30000,  // Increase from default 5000ms
    poolOptions: {
      workers: {
        wrangler: { configPath: './wrangler.jsonc' },
      },
    },
  },
});

✅ Add retry logic for flaky tests:

describe('Workflow tests', () => {
  it.retry(3)('should complete workflow', async () => {
    // Test code
  });
});

✅ Use proper test isolation:

import { beforeEach, afterEach } from 'vitest';

let instance: WorkflowInstance;

beforeEach(async () => {
  instance = await env.MY_WORKFLOW.create({
    params: { userId: '123' }
  });
});

afterEach(async () => {
  if (instance) {
    try {
      await instance.terminate();
    } catch (error) {
      // Instance may already be terminated
    }
  }
});

Workaround: 1. Increase test timeouts for CI 2. Add retry logic for flaky tests 3. Use proper test isolation 4. Consider mocking workflows in unit tests, testing real workflows in integration tests

Source: cloudflare/workers-sdk#10600 Status: Ongoing investigation

---

Additional Troubleshooting Tips

Workflow Instance Stuck in "Running" State

Possible Causes: 1. Step is sleeping for long duration 2. Step is waiting for event that never arrives 3. Step is retrying with long backoff

Solution:

# Check detailed instance status
npx wrangler workflows instances describe my-workflow <instance-id>

# Look for:
# - Sleep state (shows wake time)
# - waitForEvent state (shows event type and timeout)
# - Retry history (shows attempts and delays)

---

Step Returns Undefined

Cause: Missing return statement in step callback

Solution:

// ❌ Bad - no return
const result = await step.do('get data', async () => {
  const data = await fetchData();
  // Missing return!
});
console.log(result);  // undefined

// ✅ Good - explicit return
const result = await step.do('get data', async () => {
  const data = await fetchData();
  return data;  // ✅ Return the value
});

---

Payload Too Large Error

Error:

Payload size exceeds limit

Cause: Workflow parameters or step outputs exceed 128 KB

Solution:

// ❌ Bad - large payload
await env.MY_WORKFLOW.create({
  params: {
    largeData: hugeArray  // >128 KB
  }
});

// ✅ Good - store in R2/KV, pass reference
const key = `workflow-data/${crypto.randomUUID()}`;
await env.MY_BUCKET.put(key, JSON.stringify(hugeArray));

await env.MY_WORKFLOW.create({
  params: {
    dataKey: key  // Just pass the key
  }
});

---

Getting Help

If you encounter issues not listed here:

1. Check Cloudflare Status: https://www.cloudflarestatus.com/ 2. Search GitHub Issues: https://github.com/cloudflare/workers-sdk/issues 3. Cloudflare Discord: https://discord.gg/cloudflaredev 4. Cloudflare Community: https://community.cloudflare.com/ 5. Official Docs: https://developers.cloudflare.com/workflows/

When reporting issues, include:

• Workflow code (sanitized)
• Wrangler configuration
• Error messages and stack traces
• Workflow instance ID
• Steps to reproduce
• Expected vs actual behavior

---

Last Updated: 2025-10-22 Maintainer: Jeremy Dawes | jeremy@jezweb.net

Cloudflare Workflows - Production Patterns

Last Updated: 2025-10-22

This document provides battle-tested patterns for building production-ready Cloudflare Workflows.

---

Table of Contents

1. Idempotency Patterns 2. Error Handling Patterns 3. Long-Running Process Patterns 4. Human-in-the-Loop Patterns 5. Workflow Chaining Patterns 6. Testing Patterns 7. Monitoring Patterns

---

Idempotency Patterns

Pattern 1: Idempotency Keys

Problem: Workflow steps may execute multiple times due to retries.

Solution: Use idempotency keys to ensure operations execute only once.

export class PaymentWorkflow extends WorkflowEntrypoint<Env, PaymentParams> {
  async run(event: WorkflowEvent<PaymentParams>, step: WorkflowStep) {
    const { orderId, amount } = event.payload;

    // Generate idempotency key from workflow instance ID + step name
    const idempotencyKey = `${event.instanceId}-charge-payment`;

    const paymentResult = await step.do('charge payment', async () => {
      // Check if already processed
      const existing = await this.env.KV.get(`payment:${idempotencyKey}`);
      if (existing) {
        console.log('Payment already processed, returning cached result');
        return JSON.parse(existing);
      }

      // Process payment
      const response = await fetch('https://payment-gateway.example.com/charge', {
        method: 'POST',
        headers: {
          'Idempotency-Key': idempotencyKey  // Payment gateway checks this
        },
        body: JSON.stringify({ orderId, amount })
      });

      const result = await response.json();

      // Cache result
      await this.env.KV.put(
        `payment:${idempotencyKey}`,
        JSON.stringify(result),
        { expirationTtl: 86400 }  // 24 hours
      });

      return result;
    });

    return { orderId, transactionId: paymentResult.transactionId };
  }
}

---

Pattern 2: Database Upsert for Idempotency

await step.do('create order', async () => {
  // Use INSERT OR REPLACE to make idempotent
  await this.env.DB.prepare(`
    INSERT INTO orders (id, user_id, amount, status, created_at)
    VALUES (?, ?, ?, ?, ?)
    ON CONFLICT(id) DO UPDATE SET
      user_id = excluded.user_id,
      amount = excluded.amount,
      updated_at = CURRENT_TIMESTAMP
  `).bind(
    orderId,
    userId,
    amount,
    'pending',
    new Date().toISOString()
  ).run();

  return { orderId };
});

---

Error Handling Patterns

Pattern 1: Categorize Errors for Retry Logic

async function shouldRetry(error: Error): Promise<boolean> {
  // Don't retry on client errors (4xx)
  if (error.message.includes('400') ||
      error.message.includes('401') ||
      error.message.includes('403') ||
      error.message.includes('404')) {
    return false;
  }

  // Retry on server errors (5xx) and network errors
  return true;
}

await step.do('call API', async () => {
  try {
    const response = await fetch('https://api.example.com/data');

    if (!response.ok) {
      const error = new Error(`API error: ${response.status}`);

      if (!await shouldRetry(error)) {
        throw new NonRetryableError(error.message);
      }

      throw error;  // Will retry
    }

    return await response.json();
  } catch (error) {
    if (error instanceof NonRetryableError) {
      throw error;
    }

    // Network error - retry
    throw error;
  }
});

---

Pattern 2: Circuit Breaker

export class CircuitBreaker {
  constructor(
    private kv: KVNamespace,
    private serviceName: string,
    private threshold: number = 5,
    private resetTime: number = 60000  // 1 minute
  ) {}

  async call<T>(fn: () => Promise<T>): Promise<T> {
    const key = `circuit:${this.serviceName}`;
    const state = await this.kv.get(key, 'json') as {
      failures: number;
      lastFailure: number;
    } | null;

    // Check if circuit is open
    if (state && state.failures >= this.threshold) {
      const elapsed = Date.now() - state.lastFailure;

      if (elapsed < this.resetTime) {
        throw new NonRetryableError(
          `Circuit breaker open for ${this.serviceName}`
        );
      }
    }

    try {
      const result = await fn();

      // Reset on success
      await this.kv.delete(key);

      return result;
    } catch (error) {
      // Increment failure count
      const newState = {
        failures: (state?.failures || 0) + 1,
        lastFailure: Date.now()
      };

      await this.kv.put(key, JSON.stringify(newState), {
        expirationTtl: this.resetTime / 1000
      });

      throw error;
    }
  }
}

// Usage
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const circuitBreaker = new CircuitBreaker(this.env.KV, 'external-api');

    await step.do('call external API', async () => {
      return await circuitBreaker.call(async () => {
        const response = await fetch('https://external-api.example.com/data');
        return await response.json();
      });
    });
  }
}

---

Pattern 3: Graceful Degradation

await step.do('fetch user preferences', async () => {
  try {
    const response = await fetch(`https://api.example.com/users/${userId}/preferences`);
    if (!response.ok) throw new Error('Failed to fetch preferences');
    return await response.json();
  } catch (error) {
    console.warn('Failed to fetch preferences, using defaults:', error);

    // Fallback to defaults
    return {
      theme: 'light',
      language: 'en',
      notifications: true
    };
  }
});

---

Long-Running Process Patterns

Pattern 1: Polling with Exponential Backoff

export class VideoProcessingWorkflow extends WorkflowEntrypoint<Env, VideoParams> {
  async run(event: WorkflowEvent<VideoParams>, step: WorkflowStep) {
    const { videoId } = event.payload;

    // Submit video for processing
    const jobId = await step.do('submit video', async () => {
      const response = await fetch('https://processor.example.com/jobs', {
        method: 'POST',
        body: JSON.stringify({ videoId })
      });
      const data = await response.json();
      return data.jobId;
    });

    // Poll for completion with exponential backoff
    let complete = false;
    let attempt = 0;
    const maxAttempts = 20;

    while (!complete && attempt < maxAttempts) {
      // Wait with exponential backoff: 10s, 20s, 40s, ...
      const delay = Math.min(10 * Math.pow(2, attempt), 300);  // Max 5 minutes
      await step.sleep(`wait attempt ${attempt}`, `${delay} seconds`);

      const status = await step.do(`check status attempt ${attempt}`, async () => {
        const response = await fetch(
          `https://processor.example.com/jobs/${jobId}/status`
        );
        return await response.json();
      });

      if (status.state === 'complete') {
        complete = true;
      } else if (status.state === 'failed') {
        throw new NonRetryableError(`Processing failed: ${status.error}`);
      }

      attempt++;
    }

    if (!complete) {
      throw new Error('Processing timeout after maximum attempts');
    }

    return { videoId, jobId, status: 'complete' };
  }
}

---

Pattern 2: Progress Tracking

export class DataMigrationWorkflow extends WorkflowEntrypoint<Env, MigrationParams> {
  async run(event: WorkflowEvent<MigrationParams>, step: WorkflowStep) {
    const { totalRecords, batchSize } = event.payload;
    const batches = Math.ceil(totalRecords / batchSize);

    for (let i = 0; i < batches; i++) {
      const progress = await step.do(`migrate batch ${i}`, async () => {
        const offset = i * batchSize;

        // Migrate batch
        await this.migrateBatch(offset, batchSize);

        // Update progress in DB
        const percentage = Math.round(((i + 1) / batches) * 100);
        await this.env.DB.prepare(`
          UPDATE migration_jobs
          SET progress = ?, updated_at = ?
          WHERE id = ?
        `).bind(percentage, new Date().toISOString(), event.payload.jobId).run();

        return { batch: i + 1, total: batches, percentage };
      });

      console.log(`Progress: ${progress.percentage}%`);

      // Small delay between batches to avoid overwhelming database
      if (i < batches - 1) {
        await step.sleep(`pause before batch ${i + 1}`, '1 second');
      }
    }

    return { status: 'complete', batches };
  }

  private async migrateBatch(offset: number, limit: number) {
    // Migration logic
  }
}

---

Human-in-the-Loop Patterns

Pattern 1: Approval with Timeout and Escalation

export class ApprovalWorkflow extends WorkflowEntrypoint<Env, ApprovalParams> {
  async run(event: WorkflowEvent<ApprovalParams>, step: WorkflowStep) {
    const { requestId, amount } = event.payload;

    // Send to primary approver
    await step.do('notify primary approver', async () => {
      await this.sendApprovalRequest('manager@example.com', requestId);
    });

    // Wait 48 hours for approval
    let approved: boolean;
    let approver: string;

    try {
      const decision = await step.waitForEvent<ApprovalEvent>(
        'wait for primary approval',
        { type: 'approval-decision', timeout: '48 hours' }
      );

      approved = decision.approved;
      approver = decision.approverId;
    } catch (error) {
      // Timeout - escalate to senior manager
      console.log('Primary approval timeout, escalating');

      await step.do('notify senior approver', async () => {
        await this.sendApprovalRequest('senior-manager@example.com', requestId);
      });

      // Wait another 24 hours
      const escalatedDecision = await step.waitForEvent<ApprovalEvent>(
        'wait for escalated approval',
        { type: 'approval-decision', timeout: '24 hours' }
      );

      approved = escalatedDecision.approved;
      approver = escalatedDecision.approverId;
    }

    if (approved) {
      await step.do('execute approved action', async () => {
        // Execute the action
      });
    }

    return { requestId, approved, approver };
  }

  private async sendApprovalRequest(to: string, requestId: string) {
    // Send notification
  }
}

---

Workflow Chaining Patterns

Pattern 1: Parent-Child Workflows

export class OrderWorkflow extends WorkflowEntrypoint<Env, OrderParams> {
  async run(event: WorkflowEvent<OrderParams>, step: WorkflowStep) {
    const { orderId } = event.payload;

    // Step 1: Process payment (separate workflow)
    const paymentWorkflow = await step.do('start payment workflow', async () => {
      const instance = await this.env.PAYMENT_WORKFLOW.create({
        params: { orderId, amount: event.payload.amount }
      });
      return { instanceId: instance.id };
    });

    // Step 2: Wait for payment to complete
    let paymentComplete = false;

    while (!paymentComplete) {
      await step.sleep('wait for payment', '30 seconds');

      const paymentStatus = await step.do('check payment status', async () => {
        const instance = await this.env.PAYMENT_WORKFLOW.get(
          paymentWorkflow.instanceId
        );
        return await instance.status();
      });

      if (paymentStatus.status === 'complete') {
        paymentComplete = true;
      } else if (paymentStatus.status === 'errored') {
        throw new Error(`Payment failed: ${paymentStatus.error}`);
      }
    }

    // Step 3: Start fulfillment workflow
    await step.do('start fulfillment workflow', async () => {
      await this.env.FULFILLMENT_WORKFLOW.create({
        params: { orderId }
      });
    });

    return { orderId, status: 'processing' };
  }
}

---

Testing Patterns

Pattern 1: Mock External APIs

import { describe, it, expect, beforeEach } from 'vitest';
import { unstable_dev } from 'wrangler';

describe('PaymentWorkflow', () => {
  let worker;

  beforeEach(async () => {
    worker = await unstable_dev('src/index.ts', {
      experimental: { disableExperimentalWarning: true }
    });
  });

  it('should process payment successfully', async () => {
    // Mock fetch to return success
    globalThis.fetch = async (url: string) => {
      if (url.includes('payment-gateway')) {
        return new Response(JSON.stringify({
          transactionId: 'TXN-123',
          status: 'success'
        }));
      }
      return new Response('Not found', { status: 404 });
    };

    const response = await worker.fetch('/workflows/create', {
      method: 'POST',
      body: JSON.stringify({
        orderId: 'ORD-123',
        amount: 99.99
      })
    });

    const data = await response.json();
    expect(data.id).toBeDefined();
  });
});

---

Monitoring Patterns

Pattern 1: Structured Logging

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    this.log('info', 'Workflow started', {
      instanceId: event.instanceId,
      params: event.payload
    });

    try {
      await step.do('process data', async () => {
        this.log('info', 'Processing data', { userId: event.payload.userId });
        // Process
        return { processed: true };
      });

      this.log('info', 'Workflow completed successfully', {
        instanceId: event.instanceId
      });
    } catch (error) {
      this.log('error', 'Workflow failed', {
        instanceId: event.instanceId,
        error: error instanceof Error ? error.message : 'Unknown error'
      });
      throw error;
    }
  }

  private log(level: string, message: string, data: any) {
    console.log(JSON.stringify({
      level,
      message,
      timestamp: new Date().toISOString(),
      ...data
    }));
  }
}

---

Pattern 2: Metrics Tracking

await step.do('track metrics', async () => {
  const metrics = {
    workflowId: event.instanceId,
    stepName: 'payment-processing',
    duration: performance.now() - startTime,
    status: 'success',
    timestamp: new Date().toISOString()
  };

  // Store in Analytics Engine
  await this.env.ANALYTICS.writeDataPoint(metrics);

  return metrics;
});

---

Best Practices Summary

Always Do

1. Use idempotency keys for external API calls 2. Categorize errors - retry on transient failures, fail fast on terminal errors 3. Log structured data - JSON logs for easy querying 4. Track progress - update database for long-running processes 5. Use exponential backoff - for polling and retries 6. Test workflows - unit tests with mocked dependencies 7. Monitor metrics - track success rates, durations, errors

Never Do

1. Don't retry non-idempotent operations infinitely - use retry limits 2. Don't ignore timeout errors - handle gracefully with fallbacks 3. Don't block on external events without timeout - always set timeout 4. Don't assume steps execute in order - each step is independent 5. Don't return non-serializable values - only JSON-compatible types 6. Don't store sensitive data in workflow state - use KV/D1 instead 7. Don't forget to clean up resources - terminate unused workflow instances

---

Last Updated: 2025-10-22 Maintainer: Jeremy Dawes | jeremy@jezweb.net