Cloudflare Workflows

Status: Production Ready ✅ (GA since April 2025) Last Updated: 2026-01-09 Dependencies: cloudflare-worker-base (for Worker setup) Latest Versions: [email protected], @cloudflare/[email protected]

Recent Updates (2025):

• April 2025: Workflows GA release - waitForEvent API, Vitest testing, CPU time metrics, 4,500 concurrent instances
• October 2025: Instance creation rate 10x faster (100/sec), concurrency increased to 10,000
• 2025 Limits: Max steps 1,024, state persistence 1MB/step (100MB-1GB per instance), event payloads 1MB, CPU time 5 min max
• Testing: cloudflare:test module with introspectWorkflowInstance, disableSleeps, mockStepResult, mockEvent modifiers
• Platform: Waiting instances don't count toward concurrency, retention 3-30 days, subrequests 50-1,000

Quick Start (5 Minutes)

# 1. Scaffold project
npm create cloudflare@latest my-workflow -- --template cloudflare/workflows-starter --git --deploy false
cd my-workflow

# 2. Configure wrangler.jsonc
{
  "name": "my-workflow",
  "main": "src/index.ts",
  "compatibility_date": "2025-11-25",
  "workflows": [{
    "name": "my-workflow",
    "binding": "MY_WORKFLOW",
    "class_name": "MyWorkflow"
  }]
}

# 3. Create workflow (src/index.ts)
import { WorkflowEntrypoint, WorkflowStep, WorkflowEvent } from 'cloudflare:workers';

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    const result = await step.do('process', async () => { /* work */ });
    await step.sleep('wait', '1 hour');
    await step.do('continue', async () => { /* more work */ });
  }
}

# 4. Deploy and test
npm run deploy
npx wrangler workflows instances list my-workflow

CRITICAL: Extends WorkflowEntrypoint, implements run() with step methods, bindings in wrangler.jsonc

Known Issues Prevention

This skill prevents 12 documented errors with Cloudflare Workflows.

Issue #1: waitForEvent Skips Events After Timeout in Local Dev

Error: Events sent after a waitForEvent() timeout are ignored in subsequent waitForEvent() calls Environment: Local development (wrangler dev) only - works correctly in production Source: GitHub Issue #11740

Why It Happens: Bug in miniflare that was fixed in production (May 2025) but not ported to local emulator. After a timeout, the event queue becomes corrupted for that instance.

Prevention:

• Test waitForEvent timeout scenarios in production/staging, not local dev
• Avoid chaining multiple waitForEvent() calls where timeouts are expected

Example of Bug:

export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
  async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
    for (let i = 0; i < 3; i++) {
      try {
        const evt = await step.waitForEvent(`wait-${i}`, {
          type: 'user-action',
          timeout: '5 seconds'
        });
        console.log(`Iteration ${i}: Received event`);
      } catch {
        console.log(`Iteration ${i}: Timeout`);
      }
    }
  }
}
// In wrangler dev:
// - Iteration 1: ✅ receives event
// - Iteration 2: ⏱️ times out (expected)
// - Iteration 3: ❌ does not receive event (BUG - event is sent but ignored)

Status: Known bug, fix pending for miniflare.

Issue #2: getPlatformProxy() Fails With Workflow Bindings

Error: MiniflareCoreError [ERR_RUNTIME_FAILURE]: The Workers runtime failed to start Message: Worker's binding refers to service with named entrypoint, but service has no such entrypoint Source: GitHub Issue #9402

Why It Happens: getPlatformProxy() from wrangler package doesn't support Workflow bindings (similar to how it handles Durable Objects). This blocks Next.js integration and local CLI scripts.

Prevention:

• Option 1: Comment out workflow bindings when using getPlatformProxy()
• Option 2: Create separate wrangler.cli.jsonc without workflows for CLI scripts
• Option 3: Access workflow bindings directly via deployed worker, not proxy

// Workaround: Separate config for CLI scripts
// wrangler.cli.jsonc (no workflows)
{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-20"
  // workflows commented out
}

// Use in script:
import { getPlatformProxy } from 'wrangler';
const { env } = await getPlatformProxy({ configPath: './wrangler.cli.jsonc' });

Status: Known limitation, fix planned (filter workflows similar to DOs).

Issue #3: Workflow Instance Lost After Immediate Redirect (Local Dev)

Error: Instance ID returned but instance.not_found when queried Environment: Local development (wrangler dev) only - works correctly in production Source: GitHub Issue #10806

Why It Happens: Returning a redirect immediately after workflow.create() causes request to "soft abort" before workflow initialization completes (single-threaded execution in dev).

Prevention: Use ctx.waitUntil() to ensure workflow initialization completes before redirect:

export default {
  async fetch(req: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const workflow = await env.MY_WORKFLOW.create({ params: { userId: '123' } });

    // ✅ Ensure workflow initialization completes
    ctx.waitUntil(workflow.status());

    return Response.redirect('/dashboard', 302);
  }
};

Status: Fixed in recent wrangler versions (post-Sept 2025), but workaround still recommended for compatibility.

Issue #4: Vitest Tests Unreliable in CI Environments

Error: [vitest-worker]: Timeout calling "resolveId" Environment: CI/CD pipelines (GitLab, GitHub Actions) - works locally Source: GitHub Issue #10600

Why It Happens: @cloudflare/vitest-pool-workers has resource constraint issues in CI containers, affecting workflow tests more than other worker types.

Prevention:

1. Increase testTimeout in vitest config:

   export default defineWorkersConfig({
     test: {
       testTimeout: 60_000 // Default: 5000ms
     }
   });
   

2. Check CI resource limits (CPU/memory)
3. Use isolatedStorage: false if not testing storage isolation
4. Consider testing against deployed instances instead of vitest for critical workflows

Status: Known issue, investigating (Internal: WOR-945).

Issue #5: Instance restart() and terminate() Not Implemented in Local Dev

Error: Error: Not implemented yet when calling instance.restart() or instance.terminate() Environment: Local development (wrangler dev) only - works in production Source: GitHub Issue #11312

Why It Happens: Instance management APIs not yet implemented in miniflare. Additionally, instance status shows running even when workflow is sleeping.

Prevention: Test instance lifecycle management (pause/resume/terminate) in production or staging environment until local dev support is added.

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

// ❌ Fails in wrangler dev
await instance.restart();    // Error: Not implemented yet
await instance.terminate();  // Error: Not implemented yet

// ✅ Works in production

Status: Known limitation, no timeline for local dev support.

Is