/workers-debug

name: cloudflare-workers:debug
description: Interactive debugging workflow for Cloudflare Workers. Diagnoses deployment errors, runtime issues, and performance problems with step-by-step fixes.
allowed-tools:
  - Read
  - Grep
  - Bash
  - AskUserQuestion
  - Glob

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

**For Runtime Errors**: 4. Read main worker file (`src/index.ts` common location) 5. Check for uncaught exceptions 6. Review error handling patterns

**For Build Errors**: 4. Read `vite.config.ts` or `webpack.config.js` 5. Check `tsconfig.json` for misconfigurations 6. Review recent package.json changes

**For Binding Errors**: 4. Verify binding configuration in wrangler config 5. Check binding usage in worker code 6. Verify binding names match

Phase 4: Diagnosis - Identify Root Cause

Analyze findings to determine the issue:

**Common Deployment Errors**:

**Error**: "Authentication required"

• **Cause**: Not logged in or token expired
• **Fix**: Run `wrangler login` or refresh API token

**Error**: "Route already exists"

• **Cause**: Conflicting routes in different workers
• **Fix**: Check Cloudflare dashboard for route conflicts

**Error**: "Bundle too large"

• **Cause**: Worker exceeds 1MB limit (free) or 10MB (paid)
• **Fix**: Reduce dependencies, use code splitting

**Common Runtime Errors**:

**Error**: "Uncaught TypeError: Cannot read property"

• **Cause**: Accessing undefined object/variable
• **Fix**: Add null checks, use optional chaining

**Error**: "D1_ERROR: no such table"

• **Cause**: Database table doesn't exist or migration not run
• **Fix**: Run migrations with `wrangler d1 execute`

**Error**: "KV.get is not a function"

• **Cause**: Binding name mismatch or not configured
• **Fix**: Verify binding name in wrangler.jsonc matches code

**Common Performance Issues**:

**Symptom**: Slow response times (>1s)

• **Causes**: Large bundle, no caching, slow external APIs
• **Fixes**: Enable Cache API, reduce bundle, optimize queries

**Symptom**: CPU time exceeded

• **Causes**: Heavy computation, large loops, inefficient algorithms
• **Fixes**: Optimize algorithms, use async operations, cache results

**Common Build Errors**:

**Error**: "Module not found"

• **Cause**: Missing dependency or incorrect import path
• **Fix**: Install dependency or fix import path

**Error**: "TypeScript errors"

• **Cause**: Type mismatches, strict mode violations
• **Fix**: Fix type errors or adjust tsconfig.json

Phase 5: Fix Recommendation

Provide specific, actionable fix for the identified issue:

**Format**:

## Root Cause
[Explanation of what's causing the issue]

## Fix
[Step-by-step instructions]

## Prevention
[How to avoid this in the future]

## Related
[Links to relevant docs or skills]

**Example**:

## Root Cause
Your Worker is failing because the KV binding name in code (`CACHE`) doesn't match
the binding name in wrangler.jsonc (`MY_KV`).

## Fix
1. Open wrangler.jsonc
2. Change the KV binding name to match your code:
   ```jsonc
   {
     "kv_namespaces": [
       { "binding": "CACHE", "id": "xxx" }
     ]
   }

3. Redeploy: `bunx wrangler deploy`

Alternatively, update your code to use `MY_KV` instead of `CACHE`.

Prevention

• Use consistent naming between config and code
• Define binding types in TypeScript for autocomplete
• Add binding name validation in CI/CD

Related

• workers-testing skill: Mock KV bindings in tests
• Binding Docs: https://developers.cloudflare.com/workers/configuration/bindings/

### Phase 6: Apply Fix (Optional)

Ask user if they want help applying the fix:

**Question**: "Would you like me to apply this fix?"
- Options:
  - Yes, apply the fix automatically (Recommended)
  - No, I'll apply it manually
  - Show me the exact changes first

**If "Yes"**:
- Use Edit or Write tools to apply fix
- Run validation command if applicable
- Confirm fix was applied successfully

**If "Show changes first"**:
- Display exact diff of proposed changes
- Ask for confirmati