secondsky/claude-skills / plugins/cloudflare-workflows/skills/cloudflare-workflows
cloudflare-workflows
VerifiedCloudflare Workflows for durable long-running execution. Use for multi-step workflows, retries, state persistence, or encountering NonRetryableError, execution failed errors.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.5 KB |
| references/2025-features.md | markdown | 7.9 KB |
| references/common-issues.md | markdown | 9.9 KB |
| references/limits-quotas.md | markdown | 8.7 KB |
| references/metrics-analytics.md | markdown | 11.7 KB |
| references/production-checklist.md | markdown | 11.8 KB |
| references/troubleshooting.md | markdown | 15.1 KB |
| references/workflow-patterns.md | markdown | 15.2 KB |
| references/wrangler-commands.md | markdown | 6.6 KB |
| templates/basic-workflow.ts | script | 3.4 KB |
| templates/circuit-breaker-workflow.ts | script | 12.6 KB |
| templates/parallel-execution-workflow.ts | script | 8.6 KB |
| templates/scheduled-workflow.ts | script | 7.2 KB |
| templates/worker-trigger.ts | script | 6.6 KB |
| templates/workflow-with-events.ts | script | 9.2 KB |
| templates/workflow-with-retries.ts | script | 6.2 KB |
| templates/wrangler-workflows-config.jsonc | other | 3.8 KB |
references/limits-quotas.md
View on GitHub# Cloudflare Workflows Limits & Quotas
Complete reference for all Cloudflare Workflows limits with workarounds and optimization strategies.
## Instance Limits
| Limit | Value | Notes |
|-------|-------|-------|
| Max running instances | 100 per workflow | Queued instances wait |
| Max queued instances | 10,000 per workflow | Oldest dropped if exceeded |
| Instance retention | 7 days | After completion/failure |
| Instance ID length | 64 characters | Custom IDs must fit |
| Max instances per Worker request | No hard limit | Rate limits apply |
### Workarounds for Instance Limits
**High Volume Processing**:
```typescript
// Bad: Create many instances at once
for (const item of items) {
await env.MY_WORKFLOW.create({ params: { item } });
}
// Good: Batch processing in single workflow
await env.MY_WORKFLOW.create({
params: { items: items.slice(0, 1000) }
});
```
**Instance Management**:
```typescript
// Check running instances before creating new ones
const instances = await env.MY_WORKFLOW.list();
const running = instances.filter(i => i.status === 'running');
if (running.length >= 90) {
// Wait or queue externally
throw new Error('Too many running instances');
}
```
---
## Step Limits
| Limit | Value | Notes |
|-------|-------|-------|
| Max steps per instance | 1,000 | Across all step types |
| Step name length | 256 characters | Must be unique per instance |
| Step CPU time | 30 seconds | Per step.do() execution |
| Step wall-clock time | 15 minutes | Including I/O wait |
| Max concurrent steps | 1 | Sequential only |
### Step Limit Workarounds
**Breaking Large Operations into Batches**:
```typescript
// Bad: Single step with many items (may hit 30s limit)
await step.do('process all', async () => {
for (const item of items) {
await processItem(item); // 1000 items × 0.1s = 100s
}
});
// Good: Batched steps
const batchSize = 100;
for (let i = 0; i < items.length; i += batchSize) {
await step.do(`batch ${Math.floor(i/batchSize)}`, async () => {
const batch = items.slice(i, i + batchSize);
return Promise.all(batch.map(processItem));
});
}
```
**Avoiding Step Limit Exhaustion**:
```typescript
// Bad: One step per item (hits 1000 step limit)
for (const item of items) {
await step.do(`process ${item.id}`, () => process(item));
}
// Good: Batch items into fewer steps
const chunks = chunkArray(items, 10);
for (let i = 0; i < chunks.length; i++) {
await step.do(`batch ${i}`, async () => {
return Promise.all(chunks[i].map(process));
});
}
```
---
## Payload & Data Limits
| Limit | Value | Notes |
|-------|-------|-------|
| Step return value | 128 KB | JSON serialized |
| Workflow params | 128 KB | Input payload |
| Event payload | 128 KB | sendEvent data |
| Total state per instance | 1 MB | Sum of all step results |
### Payload Limit Workarounds
**Large Data Handling with KV/R2**:
```typescript
// Bad: Return large data from step
await step.do('fetch data', async () => {
const data = await fetchLargeDataset(); // 500KB
return data; // ERROR: exceeds 128KB
});
// Good: Store in KV, return key
await step.do('fetch and store', async () => {
const data = await fetchLargeDataset();
const key = `workflow-${event.instanceId}-data`;
await env.KV.put(key, JSON.stringify(data));
return { dataKey: key };
});
// Later step retrieves if needed
await step.do('process data', async () => {
const key = previousResult.dataKey;
const data = JSON.parse(await env.KV.get(key));
return processData(data);
});
```
**Streaming Large Responses**:
```typescript
// For very large data, use R2
await step.do('store to r2', async () => {
const data = await fetchHugeDataset(); // 10MB
await env.R2.put(`workflow/${event.instanceId}/data.json`, JSON.stringify(data));
return { stored: true, key: `workflow/${event.instanceId}/data.json` };
});
```
---
## Duration Limits
| Limit | Value | Notes |
|-------|-------|-------|
| Max workflow duration | 1 year | Total wall-clock time |
| Sleep duration | No limit | Can sleep for months |
| waitForEvent timeout | No default | Set explicitly |
| Step execution timeout | 15 minutes | Wall-clock time |
### Duration Best Practices
**Long-Running Workflows**:
```typescript
// Workflow can run for months
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
// Start immediately
await step.do('start', () => notifyStart());
// Wait for a month
await step.sleep('wait for billing cycle', '30 days');
// Continue processing
await step.do('monthly task', () => runMonthlyTask());
// This is fine - workflows can last up to 1 year
}
```
**waitForEvent with Timeout**:
```typescript
// Always set timeout to prevent indefinite waiting
const approval = await step.waitForEvent('wait for approval', 'user.approved', {
timeout: '7 days'
});
if (!approval) {
throw new NonRetryableError('Approval timeout - escalating');
}
```
---
## Retry Limits
| Limit | Default | Max |
|-------|---------|-----|
| Retry attempts | 3 | Configurable |
| Retry delay | Exponential | Configurable |
| Max retry delay | 1 hour | Capped |
### Retry Configuration
```typescript
// Configure retries per step
await step.do('flaky api', {
retries: {
limit: 5, // Max 5 retries
delay: '10 seconds', // Initial delay
backoff: 'exponential' // 10s, 20s, 40s, 80s, 160s
}
}, async () => {
return await callFlakyAPI();
});
// Disable retries for idempotency-unsafe operations
await step.do('one-time action', {
retries: { limit: 0 }
}, async () => {
return await nonIdempotentAction();
});
```
---
## Rate Limits
| Operation | Limit | Period |
|-----------|-------|--------|
| Instance creation | 1,000/min | Per workflow |
| sendEvent | 1,000/min | Per instance |
| Status queries | 10,000/min | Per account |
| List instances | 100/min | Per workflow |
### Rate Limit Handling
```typescript
// Implement rate limiting for bulk operations
async function createInstancesWithRateLimit(
workflow: Workflow,
params: any[],
ratePerMinute = 500
) {
const delayMs = 60000 / ratePerMinute;
const results = [];
for (const param of params) {
const instance = await workflow.create({ params: param });
results.push(instance);
await new Promise(r => setTimeout(r, delayMs));
}
return results;
}
```
---
## Cost Considerations
| Resource | Price | Notes |
|----------|-------|-------|
| Requests | $0.15/million | Instance creation + each step |
| Duration | $0.02/million GB-s | CPU time only |
| Sleep | FREE | No CPU usage |
| waitForEvent | FREE | While waiting |
### Cost Optimization Examples
**Use Sleep Instead of Polling**:
```typescript
// Expensive: Polling loop (10 steps = 10 requests)
for (let i = 0; i < 10; i++) {
const ready = await step.do(`check ${i}`, () => checkReady());
if (ready) break;
await step.sleep('wait', '1 minute'); // Free
}
// Cheaper: Single sleep then check
await step.sleep('wait for processing', '10 minutes'); // Free
await step.do('verify', () => verifyComplete()); // 1 request
```
**Consolidate Steps**:
```typescript
// Expensive: 3 steps = 3 requests
await step.do('validate', () => validate(data));
await step.do('transform', () => transform(data));
await step.do('save', () => save(data));
// Cheaper: 1 step = 1 request
await step.do('process', async () => {
const validated = await validate(data);
const transformed = await transform(validated);
return await save(transformed);
});
```
---
## Quota Check Script
Use this script to check if your workflow is within limits:
```bash
./scripts/check-workflow-limits.sh src/workflows/my-workflow.ts
```
Output example:
```
Workflow Limits Check: my-workflow
==================================
Steps Analysis:
- Total step.do() calls: 15
- Status: ✅ Within limit (1000 max)
Payload Analysis:
- Largest return statement: ~2KB estimated
- Status: ✅ Within limit (128KB max)
Duration Analysis:
- Estimated max duration: 5 minutes
- Status: ✅ Within limit (1 year max)
Cost Estimate (per 1000 workflows):
- Requests: 16,000 × $0.15/M = $0.0024
- Duration: ~0.005 GB-s × $0.02/M = ~$0
- Total: ~$0.0024 per 1000 workflows
```
---
## Quick Reference Card
```
INSTANCE LIMITS:
- Running: 100 max
- Queued: 10,000 max
- Retention: 7 days
STEP LIMITS:
- Steps/instance: 1,000 max
- CPU time/step: 30 seconds
- Wall time/step: 15 minutes
PAYLOAD LIMITS:
- Step return: 128 KB
- Params: 128 KB
- Event: 128 KB
- Total state: 1 MB
DURATION:
- Max workflow: 1 year
- Sleep: unlimited (free)
COST:
- Requests: $0.15/million
- Duration: $0.02/million GB-s
- Sleep/wait: FREE
```
---
## When to Load This Reference
Load this file when:
- User asks about workflow limits or quotas
- Designing workflows that may hit limits
- Optimizing workflow costs
- Debugging "payload too large" or "step limit exceeded" errors
- Planning high-volume workflow deployments
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |