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/troubleshooting.md
View on GitHub# Cloudflare Workflows Troubleshooting
Advanced debugging techniques, diagnostic procedures, and solutions for complex workflow issues.
## Diagnostic Decision Tree
```
Workflow Issue
│
├─ Deployment fails?
│ ├─ "Class not found" → Check exports (Section 1)
│ ├─ "Invalid configuration" → Validate wrangler.jsonc (Section 2)
│ └─ TypeScript errors → Check types (Section 3)
│
├─ Runtime error?
│ ├─ "I/O in run() method" → Move to step.do() (Section 4)
│ ├─ "Non-serializable" → Fix return values (Section 5)
│ ├─ "Step timeout" → Optimize or batch (Section 6)
│ └─ "NonRetryableError" → Check error handling (Section 7)
│
├─ Instance stuck?
│ ├─ In "queued" → Check instance limits (Section 8)
│ ├─ In "running" → Check for blocking operations (Section 9)
│ └─ In "paused" → Resume or investigate (Section 10)
│
└─ Performance issue?
├─ Slow execution → Optimize steps (Section 11)
├─ High cost → Reduce requests (Section 12)
└─ High retry rate → Fix flaky operations (Section 13)
```
---
## Section 1: Class Export Issues
### Symptom
```
Error: Workflow class "MyWorkflow" not found
```
### Diagnosis
```bash
# Check if class is exported from main entry
grep "export.*MyWorkflow" src/index.ts
# Check if class extends WorkflowEntrypoint
grep "class MyWorkflow extends WorkflowEntrypoint" src/**/*.ts
```
### Solution
**1. Export from main entry file**:
```typescript
// src/index.ts
export { MyWorkflow } from './workflows/my-workflow';
```
**2. Verify wrangler.jsonc matches**:
```jsonc
{
"workflows": [
{
"class_name": "MyWorkflow" // Must match exported class name
}
]
}
```
**3. Check for typos**:
- Class name is case-sensitive
- File name doesn't need to match class name
- But export statement must use exact class name
---
## Section 2: Configuration Issues
### Symptom
```
Error: Invalid wrangler.jsonc configuration
```
### Diagnosis
```bash
# Validate JSON syntax (strip comments)
grep -v '^[[:space:]]*//' wrangler.jsonc | jq '.'
# Check workflow configuration
./scripts/validate-workflow-config.sh
```
### Common Configuration Errors
**Missing required fields**:
```jsonc
// Wrong - missing required fields
{
"workflows": [{ "class_name": "MyWorkflow" }]
}
// Correct - all required fields
{
"workflows": [
{
"binding": "MY_WORKFLOW", // Required
"name": "my-workflow", // Required
"class_name": "MyWorkflow" // Required
}
]
}
```
**Duplicate workflow names**:
```jsonc
// Wrong - duplicate names
{
"workflows": [
{ "binding": "WF1", "name": "workflow", "class_name": "Workflow1" },
{ "binding": "WF2", "name": "workflow", "class_name": "Workflow2" }
]
}
// Correct - unique names
{
"workflows": [
{ "binding": "WF1", "name": "workflow-1", "class_name": "Workflow1" },
{ "binding": "WF2", "name": "workflow-2", "class_name": "Workflow2" }
]
}
```
**Invalid binding names**:
```jsonc
// Wrong - lowercase binding
{ "binding": "myWorkflow" }
// Correct - SCREAMING_SNAKE_CASE
{ "binding": "MY_WORKFLOW" }
```
---
## Section 3: TypeScript Errors
### Symptom
```
Type 'X' is not assignable to type 'Y'
```
### Diagnosis
```bash
# Run TypeScript check
npx tsc --noEmit
```
### Common Type Issues
**Missing Env interface**:
```typescript
// Wrong - Workflow binding not in Env
interface Env {
KV: KVNamespace;
}
// Correct - include workflow binding
interface Env {
KV: KVNamespace;
MY_WORKFLOW: Workflow; // Add this
}
```
**Incorrect generic types**:
```typescript
// Wrong - missing generics
export class MyWorkflow extends WorkflowEntrypoint {
// Correct - specify Env and Params
export class MyWorkflow extends WorkflowEntrypoint<Env, Params> {
```
**Missing workers-types**:
```bash
# Install latest types
npm install -D @cloudflare/workers-types@latest
```
---
## Section 4: I/O Context Errors
### Symptom
```
Error: Cannot perform I/O outside of a step
```
### Diagnosis
Look for `await` statements in `run()` method that are not inside `step.do()`:
```typescript
// Wrong - I/O outside step.do()
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
const data = await fetch('https://api.example.com'); // Error!
await step.do('process', async () => {
return process(data);
});
}
```
### Solution
**Move ALL I/O inside step.do()**:
```typescript
async run(event: WorkflowEvent<Params>, step: WorkflowStep) {
const data = await step.do('fetch data', async () => {
const response = await fetch('https://api.example.com');
return response.json();
});
await step.do('process', async () => {
return process(data);
});
}
```
**Also applies to**:
- `env.KV.get/put`
- `env.D1.prepare().run()`
- `env.R2.put/get`
- Any external API calls
- Database operations
---
## Section 5: Serialization Errors
### Symptom
```
Error: Cannot serialize step result
```
### Diagnosis
Check for non-JSON-serializable values in step returns:
```bash
# Find potential issues
grep -n "return.*new Date()\|return.*function\|return.*undefined" src/workflows/*.ts
```
### Non-Serializable Types
| Type | Problem | Solution |
|------|---------|----------|
| `Date` | Object, not primitive | Use `.toISOString()` |
| `undefined` | Not JSON-valid | Use `null` or omit |
| `Function` | Cannot serialize | Remove or use identifier |
| `Symbol` | Cannot serialize | Use string |
| `BigInt` | Not JSON-native | Convert to string |
| Circular refs | Infinite recursion | Break cycles |
### Solution
```typescript
// Wrong
await step.do('get data', async () => {
return {
createdAt: new Date(), // Object
callback: () => {}, // Function
value: undefined, // undefined
bigNum: 12345678901234567890n // BigInt
};
});
// Correct
await step.do('get data', async () => {
return {
createdAt: new Date().toISOString(), // String
callbackId: 'process-callback', // Identifier
value: null, // Explicit null
bigNum: '12345678901234567890' // String
};
});
```
---
## Section 6: Step Timeout Issues
### Symptom
```
Error: Step exceeded 30 second CPU limit
```
### Diagnosis
Find long-running operations:
```bash
# Find loops inside steps
grep -B5 -A10 "step\.do" src/workflows/*.ts | grep -E "for|while"
```
### Solution
**Batch large operations**:
```typescript
// Wrong - may timeout
await step.do('process all', async () => {
for (const item of largeArray) {
await processItem(item); // 1000 items × 0.1s = 100s
}
});
// Correct - batched
const batchSize = 50;
for (let i = 0; i < largeArray.length; i += batchSize) {
await step.do(`batch-${i}`, async () => {
const batch = largeArray.slice(i, i + batchSize);
return Promise.all(batch.map(processItem));
});
}
```
**Use parallel processing within batches**:
```typescript
await step.do('process batch', async () => {
return Promise.all(items.map(async (item) => {
return await processItem(item);
}));
});
```
---
## Section 7: NonRetryableError Issues
### Symptom
- Errors retry forever
- Expected failures don't stop workflow
- Missing error context
### Diagnosis
```bash
# Check NonRetryableError usage
grep -n "NonRetryableError" src/workflows/*.ts
# Check for empty constructors
grep -n "new NonRetryableError()" src/workflows/*.ts
```
### Solution
**Import NonRetryableError**:
```typescript
import { NonRetryableError } from 'cloudflare:workflows';
```
**Use descriptive messages**:
```typescript
// Wrong - no message
throw new NonRetryableError();
// Correct - descriptive
throw new NonRetryableError('Order validation failed: missing customer email');
```
**Categorize errors correctly**:
```typescript
await step.do('call api', async () => {
const response = await fetch(url);
if (!response.ok) {
// 4xx = permanent failure
if (response.status >= 400 && response.status < 500) {
throw new NonRetryableError(`Client error: ${response.status}`);
}
// 5xx = transient, will retry
throw new Error(`Server error: ${response.status}`);
}
return response.json();
});
```
---
## Section 8: Queued Instances
### Symptom
Instances stuck in "queued" status
### Diagnosis
```bash
# Check running instances
wrangler workflows instances list my-workflow --status running
# Count running (max 100)
wrangler workflows instances list my-workflow --status running | wc -l
```
### Causes
1. **100 running instances limit**: New instances wait in queue
2. **Slow step execution**: Instances don't complete fast enough
3. **Waiting for events**: Instances blocked on waitForEvent
### Solution
**Optimize workflow speed**:
- Reduce step count
- Batch operations
- Use parallel processing
**Handle backpressure**:
```typescript
// Check queue before creating new instances
export default {
async fetch(req: Request, env: Env) {
const instances = await env.MY_WORKFLOW.list();
const running = instances.filter(i => i.status === 'running');
if (running.length >= 90) {
return Response.json({
error: 'Queue full',
queuePosition: running.length
}, { status: 429 });
}
const instance = await env.MY_WORKFLOW.create({ params });
return Response.json({ id: instance.id });
}
};
```
---
## Section 9: Stuck Running Instances
### Symptom
Instances stay in "running" status indefinitely
### Diagnosis
```bash
# Find long-running instances
wrangler workflows instances list my-workflow --status running
```
### Causes
1. **Infinite loop in step.do()**: Step never completes
2. **waitForEvent without timeout**: Waiting forever
3. **Deadlock**: Waiting for external event that won't arrive
### Solution
**Always set waitForEvent timeout**:
```typescript
// Wrong - waits forever
const event = await step.waitForEvent('approval', 'user.approved');
// Correct - with timeout
const event = await step.waitForEvent('approval', 'user.approved', {
timeout: '24 hours'
});
if (!event) {
throw new NonRetryableError('Approval timeout');
}
```
**Terminate stuck instances**:
```bash
wrangler workflows instances terminate my-workflow <instance-id>
```
**Add circuit breaker**:
```typescript
await step.do('call api', async () => {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 25000);
try {
const response = await fetch(url, { signal: controller.signal });
return response.json();
} finally {
clearTimeout(timeout);
}
});
```
---
## Section 10: Paused Instances
### Symptom
Instances in "paused" status
### Causes
1. **Explicit pause**: `instance.pause()` was called
2. **System pause**: Rate limiting or maintenance
### Solution
**Resume manually**:
```bash
wrangler workflows instances resume my-workflow <instance-id>
```
**Resume programmatically**:
```typescript
const instance = await env.MY_WORKFLOW.get(instanceId);
await instance.resume();
```
---
## Section 11: Slow Execution
### Diagnosis
```bash
# Benchmark workflow
./scripts/benchmark-workflow.sh my-workflow 10
```
### Optimization Strategies
**1. Reduce step count**:
```typescript
// Slow: 3 steps
await step.do('validate', () => validate(data));
await step.do('transform', () => transform(data));
await step.do('save', () => save(data));
// Fast: 1 step
await step.do('process', async () => {
const validated = await validate(data);
const transformed = await transform(validated);
return await save(transformed);
});
```
**2. Use Promise.all()**:
```typescript
await step.do('fetch all', async () => {
const [users, orders, products] = await Promise.all([
fetch('/users').then(r => r.json()),
fetch('/orders').then(r => r.json()),
fetch('/products').then(r => r.json())
]);
return { users, orders, products };
});
```
**3. Cache expensive operations**:
```typescript
await step.do('get config', async () => {
// Check cache first
const cached = await env.KV.get('config', 'json');
if (cached) return cached;
// Fetch and cache
const config = await fetchConfig();
await env.KV.put('config', JSON.stringify(config), { expirationTtl: 3600 });
return config;
});
```
---
## Section 12: High Cost
### Diagnosis
```bash
# Check step count
grep -c "step\.do" src/workflows/*.ts
# Check for polling patterns
grep -B5 -A5 "for.*step\.do\|while.*step\.do" src/workflows/*.ts
```
### Cost Reduction Strategies
**1. Replace polling with sleep**:
```typescript
// Expensive: 10 steps
for (let i = 0; i < 10; i++) {
const done = await step.do(`check-${i}`, () => checkStatus());
if (done) break;
}
// Cheap: 2 steps + free sleep
await step.sleep('wait', '5 minutes'); // FREE
const done = await step.do('check', () => checkStatus());
```
**2. Replace polling with events**:
```typescript
// Expensive: polling
for (let i = 0; i < 60; i++) {
const status = await step.do(`poll-${i}`, () => getStatus());
if (status === 'complete') break;
await step.sleep('wait', '1 minute');
}
// Cheap: event-driven
await step.do('initiate', () => startProcess());
const event = await step.waitForEvent('complete', 'process.complete', {
timeout: '1 hour'
});
```
---
## Section 13: High Retry Rate
### Diagnosis
Check logs for retry patterns:
```bash
wrangler tail my-worker | grep -i "retry"
```
### Solutions
**1. Configure appropriate retry strategy**:
```typescript
await step.do('flaky api', {
retries: {
limit: 5,
delay: '5 seconds',
backoff: 'exponential'
}
}, async () => {
return await callFlakyAPI();
});
```
**2. Add circuit breaker**:
```typescript
const FAILURE_THRESHOLD = 5;
const RESET_TIMEOUT = 60000;
let failures = 0;
let lastFailure = 0;
await step.do('protected call', async () => {
// Check circuit breaker
if (failures >= FAILURE_THRESHOLD) {
if (Date.now() - lastFailure < RESET_TIMEOUT) {
throw new NonRetryableError('Circuit breaker open');
}
failures = 0; // Reset after timeout
}
try {
const result = await riskyOperation();
failures = 0; // Reset on success
return result;
} catch (error) {
failures++;
lastFailure = Date.now();
throw error;
}
});
```
**3. Use idempotency keys**:
```typescript
await step.do('payment', async () => {
const idempotencyKey = `${event.instanceId}-payment`;
return await fetch('https://payment.api/charge', {
method: 'POST',
headers: {
'Idempotency-Key': idempotencyKey
},
body: JSON.stringify({ amount })
});
});
```
---
## Debugging Tools Quick Reference
| Tool | Command | Purpose |
|------|---------|---------|
| Validate config | `./scripts/validate-workflow-config.sh` | Check configuration |
| Test workflow | `./scripts/test-workflow.sh` | Run test instance |
| Benchmark | `./scripts/benchmark-workflow.sh` | Measure performance |
| Check limits | `./scripts/check-workflow-limits.sh` | Validate against limits |
| List instances | `wrangler workflows instances list` | See all instances |
| Describe instance | `wrangler workflows instances describe` | Get instance details |
| View logs | `wrangler tail` | Stream real-time logs |
| TypeScript check | `npx tsc --noEmit` | Validate types |
---
## When to Load This Reference
Load this file when:
- Debugging complex workflow issues
- Errors don't match common patterns
- Need systematic diagnostic approach
- Performance optimization needed
- High retry or error rates observed
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 |