cloudflare-workers:debug

Workers Debug Command

Interactive debugging assistant for diagnosing and fixing Cloudflare Workers issues.

Execution Workflow

Phase 1: Error Category Identification

Use AskUserQuestion to understand the problem type:

Question: "What type of issue are you experiencing?"

• Options:
  • Deployment Error (wrangler deploy fails)
  • Runtime Error (worker crashes or returns 500)
  • Performance Issue (slow responses, timeouts)
  • Build Error (bundling or compilation fails)
  • Binding Error (D1, KV, R2, DO not working)
  • Authentication Error (wrangler login issues)

Phase 2: Specific Error Details

Based on category, ask follow-up questions:

If Deployment Error:

• "What error message did you receive?"
• "Does wrangler whoami work?"
• "Are you deploying to a zone-scoped worker or workers.dev?"

If Runtime Error:

• "What's the exact error message or status code?"
• "Does this happen on all requests or specific routes?"
• "Are you using any bindings (D1, KV, R2, DO)?"

If Performance Issue:

• "What's the expected vs. actual response time?"
• "When did the slowness start?"
• "Is this affecting all routes or specific endpoints?"

If Build Error:

• "What's the build error message?"
• "What bundler are you using (Vite, Webpack, esbuild)?"
• "Did you recently add dependencies?"

If Binding Error:

• "Which binding is failing (D1, KV, R2, DO, Queue)?"
• "What's the error message?"
• "Is the binding configured in wrangler.jsonc?"

If Authentication Error:

• "What command are you running?"
• "Have you run wrangler login recently?"
• "Are you using API tokens or OAuth?"

Phase 3: Investigation - Read Relevant Files

Based on error category, read files to diagnose:

For ALL categories:

1. Read wrangler.jsonc or wrangler.toml
2. Check package.json for dependencies
3. Look for recent git changes: git log -5 --oneline

For Deployment Errors: 4. Check wrangler whoami output 5. Check routes configuration 6. Look for compatibility flags