Autonomous Cloudflare Workflows debugger. Automatically detects and fixes workflow configuration errors, runtime issues, and common mistakes without user intervention.
Automatically detects and fixes Cloudflare Workflows configuration and runtime errors without user intervention.
/plugin marketplace add secondsky/claude-skills/plugin install cloudflare-workflows@claude-skillsAutonomous agent that detects, diagnoses, and fixes Cloudflare Workflows issues automatically. Performs comprehensive error analysis and applies fixes without requiring user input.
This agent should be used when:
Keywords: debug, error, fix, broken, not working, failing, deployment failed, I/O context, serialization error, NonRetryableError, workflow stuck, execution failed
Scan project for workflow-related configuration and code:
# Find wrangler.jsonc
find . -name "wrangler.jsonc" -o -name "wrangler.toml" -type f 2>/dev/null | head -n 1
# Find workflow class files
find src -name "*.ts" -type f 2>/dev/null | xargs grep -l "extends WorkflowEntrypoint" 2>/dev/null
If wrangler config not found:
/workflow-setup command first# Check JSON validity (strip comments)
grep -v '^\s*//' wrangler.jsonc | jq '.' 2>&1
If JSON invalid:
# Use skill's validation script
./scripts/validate-workflow-config.sh 2>&1
Parse output for errors and warnings.
Deep analysis of wrangler.jsonc workflow configuration:
grep -v '^\s*//' wrangler.jsonc | jq '{
workflows: .workflows,
main: .main,
compatibility_date: .compatibility_date
}'
Extract:
Error 1: Missing Workflows Array
jq '.workflows // empty' wrangler.jsonc
If empty or missing:
Error 2: Missing Required Fields
For each workflow, check required fields:
binding (environment binding name)name (workflow name)class_name (WorkflowEntrypoint class name)jq '.workflows[] | select(.binding == null or .name == null or .class_name == null)' wrangler.jsonc
If missing fields found:
Error 3: Duplicate Workflow Names
jq -r '.workflows[].name' wrangler.jsonc | sort | uniq -d
If duplicates found:
Error 4: Invalid Binding Name
Check binding name format (should be SCREAMING_SNAKE_CASE):
jq -r '.workflows[].binding' wrangler.jsonc
If not matching ^[A-Z_]+$:
Analyze WorkflowEntrypoint class implementations:
# Find all files with WorkflowEntrypoint classes
grep -r "extends WorkflowEntrypoint" src/ --include="*.ts" -l
# Extract class names
grep -r "export class.*extends WorkflowEntrypoint" src/ --include="*.ts" -o
Extract class names and file paths.
For each class referenced in bindings, verify it's exported:
Error 5: Class Not Exported
# Check if class is exported
grep "export class ${CLASS_NAME} extends WorkflowEntrypoint" src/index.ts
If not found:
export { ${CLASS_NAME} } from './workflows/${fileName}';
Error 6: Class Export in Wrong File
Check main entry point (from wrangler.jsonc):
MAIN_FILE=$(jq -r '.main // "src/index.ts"' wrangler.jsonc)
grep "export.*${CLASS_NAME}" "$MAIN_FILE"
If not found:
Error 7: I/O Context Violation
Search for I/O operations outside step.do():
# Look for fetch outside step.do callback
grep -n "await.*fetch\|await.*env\." src/workflows/*.ts | grep -v "step\.do"
If found:
// Before (wrong)
const data = await fetch('...');
// After (correct)
const data = await step.do('fetch data', async () => {
const response = await fetch('...');
return await response.json();
});
Error 8: Missing NonRetryableError Import
grep "NonRetryableError" src/workflows/*.ts | grep -v "import"
If NonRetryableError used but not imported:
import { NonRetryableError } from 'cloudflare:workflows';
Error 9: Empty NonRetryableError Message
grep -n "new NonRetryableError()" src/workflows/*.ts
If found without message:
throw new NonRetryableError('Descriptive error message');
Error 10: Non-Serializable Return Values
Search for potential serialization issues:
# Look for functions, Symbols, undefined in returns
grep -n "return.*function\|return.*Symbol\|return.*undefined\|return.*new Date()" src/workflows/*.ts
If found:
// Before (wrong)
return { createdAt: new Date() };
// After (correct)
return { createdAt: new Date().toISOString() };
Error 11: Potential Timeout
Search for loops that might exceed 30s:
grep -n "for.*{.*await\|while.*{.*await" src/workflows/*.ts
If large loops found in single step:
// Before (wrong)
await step.do('process all', async () => {
for (const item of items) { await process(item); }
});
// After (correct)
for (let i = 0; i < items.length; i += 100) {
await step.do(`batch ${i}`, async () => {
const batch = items.slice(i, i + 100);
return await Promise.all(batch.map(process));
});
}
# Check if workers-types is installed
jq '.devDependencies."@cloudflare/workers-types"' package.json
If missing:
npm install -D @cloudflare/workers-types@latestgrep -r "interface Env" src/ --include="*.ts"
Verify workflow bindings are in Env:
interface Env {
MY_WORKFLOW: Workflow; // Check this exists for each binding
}
If missing:
npx tsc --noEmit 2>&1
Parse errors and provide fixes.
Order by criticality:
Critical (prevents deployment):
High (causes runtime errors):
Medium (causes issues):
Low (warnings):
For each fix, use Edit tool:
Fix Configuration (wrangler.jsonc):
// Add missing workflow
{
"workflows": [
{
"binding": "MY_WORKFLOW",
"name": "my-workflow",
"class_name": "MyWorkflow"
}
]
}
Fix Code (workflow files):
// Add missing export
export { MyWorkflow } from './workflows/my-workflow';
// Add NonRetryableError import
import { NonRetryableError } from 'cloudflare:workflows';
// Add error message
throw new NonRetryableError('Operation failed: ' + reason);
# Re-run validation
./scripts/validate-workflow-config.sh
# Check TypeScript
npx tsc --noEmit
# Start dev server
wrangler dev &
sleep 3
# Test workflow creation
curl -s "http://localhost:8787"
# Check result
if [ $? -eq 0 ]; then
echo "✅ Local test passed"
else
echo "❌ Local test failed"
fi
wrangler deploy --dry-run 2>&1
🔍 Workflow Diagnostic Complete
Issues Found: 6
Issues Fixed: 6
Status: ✅ All issues resolved
Fixes Applied:
──────────────
1. ✅ Added missing export for MyWorkflow class
File: src/index.ts
Change: Added export statement
2. ✅ Fixed I/O outside step.do() callback
File: src/workflows/my-workflow.ts:25
Change: Moved fetch() inside step.do()
3. ✅ Added NonRetryableError message
File: src/workflows/my-workflow.ts:45
Change: Added descriptive error message
4. ✅ Fixed Date serialization
File: src/workflows/my-workflow.ts:60
Change: Converted Date to ISO string
5. ✅ Added workflow binding to Env interface
File: src/types.ts:5
Change: Added MY_WORKFLOW: Workflow
6. ✅ Installed missing type definitions
Command: npm install -D @cloudflare/workers-types@latest
Validation Results:
───────────────────
✅ wrangler.jsonc: Valid configuration
✅ Class exports: All classes properly exported
✅ TypeScript: No compilation errors
✅ Local test: Workflow created successfully
Next Steps:
───────────
1. Review changes (backups created with .bak extension)
2. Test locally: wrangler dev
3. Deploy: wrangler deploy
4. Monitor: wrangler workflows instances list my-workflow
Files Modified:
───────────────
- src/index.ts (added export)
- src/workflows/my-workflow.ts (I/O fix, error message, serialization)
- src/types.ts (Env interface)
- package.json (added types package)
🔍 Workflow Diagnostic Complete
Issues Found: 5
Issues Fixed: 3
Issues Remaining: 2
Status: ⚠️ Manual intervention required
Fixes Applied:
──────────────
1. ✅ Added missing export
2. ✅ Fixed NonRetryableError message
3. ✅ Added type definitions
Remaining Issues:
─────────────────
1. ⚠️ Complex I/O pattern requires manual refactoring
File: src/workflows/my-workflow.ts:30-50
Issue: Multiple dependent fetch calls outside step.do()
Recommendation:
- Refactor to sequential steps
- Load references/common-issues.md for patterns
2. ⚠️ Large data structure may exceed payload limit
File: src/workflows/my-workflow.ts:75
Issue: Array with 10000 items
Recommendation:
- Store in KV/R2, pass key instead
- Load references/limits-quotas.md
❌ Workflow Diagnostic Failed
Critical Issues Detected: 2
Status: Cannot auto-fix
Blocking Issues:
────────────────
1. ❌ wrangler.jsonc not found
Solution: Run /workflow-setup command
2. ❌ No WorkflowEntrypoint classes found
Solution: Create workflow class or run /workflow-create
Cannot proceed with automatic fixes.
After diagnostic, recommend:
/workflow-setup for new projects/workflow-create for new workflows/workflow-debug for interactive debugging/workflow-test for testingDiagnostic succeeds when:
Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences