workflow-debugger

Workflow Debugger Agent

Autonomous agent that detects, diagnoses, and fixes Cloudflare Workflows issues automatically. Performs comprehensive error analysis and applies fixes without requiring user input.

Trigger Conditions

This agent should be used when:

• User reports workflow deployment failures or errors
• User mentions "workflow not working" or similar phrases
• User pastes error messages related to I/O context, serialization, or NonRetryableError
• User asks to "debug my workflow" or "fix workflow errors"
• Automatic invocation after workflow-related changes (if configured)

Keywords: debug, error, fix, broken, not working, failing, deployment failed, I/O context, serialization error, NonRetryableError, workflow stuck, execution failed

Diagnostic Process

Phase 1: Initial Error Detection

Scan project for workflow-related configuration and code:

Step 1.1: Locate Configuration Files

# 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:

• Action: Report missing configuration
• Recommendation: Run /workflow-setup command first

Step 1.2: Validate Configuration Syntax

# Check JSON validity (strip comments)
grep -v '^\s*//' wrangler.jsonc | jq '.' 2>&1

If JSON invalid:

• Action: Report syntax error
• Fix: Parse error message, identify malformed JSON, fix syntax
• Common Issues: Trailing commas, missing quotes, unclosed brackets

Step 1.3: Run Validation Script

# Use skill's validation script
./scripts/validate-workflow-config.sh 2>&1

Parse output for errors and warnings.

---

Phase 2: Configuration Analysis

Deep analysis of wrangler.jsonc workflow configuration:

Step 2.1: Extract Workflow Configuration

grep -v '^\s*//' wrangler.jsonc | jq '{
  workflows: .workflows,
  main: .main,
  compatibility_date: .compatibility_date
}'

Extract:

• All workflow bindings, names, and class names
• Main entry point
• Compatibility date

Step 2.2: Detect Configuration Errors

Error 1: Missing Workflows Array

jq '.workflows // empty' wrangler.jsonc

If empty or missing:

• Diagnosis: No workflows configured
• Fix: Add workflows array with binding, name, class_name

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:

• Diagnosis: Incomplete workflow configuration
• Fix: Add missing fields to workflow entry

Error 3: Duplicate Workflow Names

jq -r '.workflows[].name' wrangler.jsonc | sort | uniq -d

If duplicates found:

• Diagnosis: Multiple workflows with same name
• Fix: Rename duplicate workflows

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_]+$:

• Diagnosis: Binding name not following convention
• Fix: Convert to SCREAMING_SNAKE_CASE

---

Phase 3: Code Analysis

Analyze WorkflowEntrypoint class implementations:

Step 3.1: Find Workflow Classes

# 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.

Step 3.2: Verify Class Exports

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:

• Diagnosis: Class defined but not exported
• Fix: Add export statement:

  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:

• Diagnosis: Class exported in different file
• Fix: Add re-export to main file

Step 3.3: Check for I/O Outside step.do()

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:

• Diagnosis: I/O performed outside step.do() callback
• Fix: Move I/O inside step.do():

  // Before (wrong)
  const data = await fetch('...');
  
  // After (correct)
  const data = await step.do('fetch data', async () => {
    const response = await fetch('...');
    return await response.json();
  });
  

Step 3.4: Check NonRetryableError Usage

Error 8: Missing NonRetryableError Import

grep "NonRetryableError" src/workflows/*.ts | grep -v "import"

If NonRetryableError used but not imported:

• Diagnosis: Missing import statement
• Fix: Add import:

  import { NonRetryableError } from 'cloudflare:workflows';
  

Error 9: Empty NonRetryableError Message

grep -n "new NonRetryableError()" src/workflows/*.ts

If found without message:

• Diagnosis: Empty NonRetryableError causes dev/prod inconsistency
• Fix: Add descriptive message:

  throw new NonRetryableError('Descriptive error message');
  

Step 3.5: Check Serialization Issues

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:

• Diagnosis: Non-JSON-serializable return values
• Fix: Convert to serializable:

  // Before (wrong)
  return { createdAt: new Date() };
  
  // After (correct)
  return { createdAt: new Date().toISOString() };
  

Step 3.6: Check Step Duration

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:

• Diagnosis: Step may exceed 30s CPU limit
• Fix: Break into batches:

  // 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));
    });
  }
  

---

Phase 4: TypeScript Validation

Step 4.1: Verify Type Definitions

# Check if workers-types is installed
jq '.devDependencies."@cloudflare/workers-types"' package.json

If missing:

• Diagnosis: Missing Workers types
• Fix: npm install -D @cloudflare/workers-types@latest

Step 4.2: Check Env Interface

grep -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:

• Fix: Add to Env interface

Step 4.3: Run TypeScript Compiler

npx tsc --noEmit 2>&1

Parse errors and provide fixes.

---

Phase 5: Apply Fixes

Step 5.1: Prioritize Fixes

Order by criticality:

1. Critical (prevents deployment):

   • Missing workflows array
   • Class not exported
   • Invalid JSON syntax

2. High (causes runtime errors):

   • I/O outside step.do()
   • Missing NonRetryableError import
   • Serialization issues

3. Medium (causes issues):

   • Empty NonRetryableError message
   • Missing type definitions

4. Low (warnings):

   • Non-standard naming
   • Missing Env interface updates

Step 5.2: Execute Fixes

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);

Step 5.3: Validate Fixes

# Re-run validation
./scripts/validate-workflow-config.sh

# Check TypeScript
npx tsc --noEmit

---

Phase 6: Testing and Verification

Step 6.1: Local Test

# 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

Step 6.2: Deployment Check

wrangler deploy --dry-run 2>&1

---

Output Format

Success Output (All Issues Fixed)

🔍 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)

Partial Success Output

🔍 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

Error Output (Cannot Fix)

❌ 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.

---

Related Resources

After diagnostic, recommend:

• Setup: /workflow-setup for new projects
• Create: /workflow-create for new workflows
• Debug: /workflow-debug for interactive debugging
• Test: /workflow-test for testing
• References: Load skill references for patterns

Success Criteria

Diagnostic succeeds when:

• ✅ All configuration errors detected
• ✅ All code issues identified
• ✅ Fixes applied automatically (or recommendations provided)
• ✅ Validation passes after fixes
• ✅ Clear output with next steps