cloudflare-workflows:debug

Workflow Debug

Overview

Interactive debugging assistant for Cloudflare Workflow instances with step-by-step diagnosis.

Prerequisites

• wrangler CLI authenticated
• Workflow deployed to Cloudflare
• Instance ID or workflow name

Steps

Step 1: Identify Instance

Use AskUserQuestion:

Question: "Which workflow instance needs debugging?"

• Header: "Instance"
• Question: "How would you like to identify the instance?"
• multiSelect: false
• Options:

  • label: "I have instance ID"

  • description: "Provide specific instance ID to debug"

  • label: "Show recent instances"

  • description: "List recent instances and select one"

  • label: "Show failed instances"

  • description: "List only failed instances"

If "I have instance ID":

• Ask for: workflow name + instance ID

If "Show recent instances":

wrangler workflows instances list ${workflowName} --limit 10

Display instances, ask user to select one

If "Show failed instances":

wrangler workflows instances list ${workflowName} --status errored --limit 10

---

Step 2: Fetch Instance Details

wrangler workflows instances describe ${workflowName} ${instanceId}

Parse Output:

• Status (running, complete, errored)
• Error message (if failed)
• Step history (which steps completed)
• Last step executed
• Retry count

Display:

Instance Details:
- ID: ${instanceId}
- Status: ${status}
- Steps Completed: ${stepsCompleted} / ${totalSteps}
- Last Step: ${lastStep}
- Error: ${errorMessage}

---

Step 3: Diagnose Issue

Based on status, provide diagnosis:

If Status = "errored":

Check error message patterns:

Pattern 1: "Cannot perform I/O on behalf of different request"

• Diagnosis: I/O outside step.do()
• Solution: Move I/O inside step.do() callbacks
• Reference: Load references/common-issues.md #1

Pattern 2: "NonRetryableError"

• Diagnosis: Permanent failure
• Solution: Check error message, fix root cause
• Reference: Load references/common-issues.md #3