workflow-debugger

name: workflow-debugger
description: Autonomous Cloudflare Workflows debugger. Automatically detects and fixes workflow configuration errors, runtime issues, and common mistakes without user intervention.
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Edit
  - Write

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: