/do-debug

name: cloudflare-durable-objects:debug
description: Interactive Durable Objects debugging workflow. Diagnoses common DO errors, configuration issues, and runtime problems with step-by-step troubleshooting.

Durable Objects Debug Command

Interactive command to diagnose and fix common Durable Objects issues. Provides step-by-step troubleshooting for configuration errors, runtime failures, and performance problems.

Overview

This command helps debug DO issues by:

• Detecting common error patterns from error messages
• Running diagnostic checks on configuration and code
• Providing specific fixes for identified issues
• Testing solutions before deployment
• Monitoring DO behavior with wrangler tail

Step 1: Gather Error Context

Use AskUserQuestion tool to understand the problem:

Question 1: Error Category

**Question**: "What type of issue are you experiencing with Durable Objects?" **Header**: "Issue Type" **Options**:

• **Deployment Error** - wrangler deploy fails with DO-related error
• Description: "Migration errors, binding issues, class export problems"
• **Runtime Error** - DO throws error during execution
• Description: "Constructor failures, storage errors, WebSocket issues"
• **Performance Issue** - DO is slow or timing out
• Description: "Slow queries, hibernation problems, memory issues"
• **Data Loss** - DO state not persisting correctly
• Description: "Data disappearing, inconsistent state, sync issues"
• **WebSocket Problem** - WebSocket connections failing or not hibernating
• Description: "Connection drops, hibernation failures, message loss"
• **Alarm Not Firing** - Scheduled alarms not executing
• Description: "Alarms not triggering, retry loops, timing issues"
• **Other/Unknown** - Not sure or different issue
• Description: "General debugging assistance needed"

Question 2: Error Message (If Applicable)

If user selected error-based category (Deployment, Runtime):

**Prompt**: "Please paste the full error message:"

Enter error message (or 'none' if no specific error):
_____________________________________________
_____________________________________________
_____________________________________________

Parse error message for known patterns:

**Deployment Error Patterns:**

• `"class_name" not found` → Class export missing
• `migrations required` → Missing migration
• `binding not found` → Binding misconfiguration
• `module not found` → Import path issue

**Runtime Error Patterns:**

• `constructor failed` → Constructor timeout/error
• `SQL error` → Query syntax or schema issue
• `WebSocket` → Hibernation or connection issue
• `alarm` → Alarm handler error
• `storage limit exceeded` → 1GB/128MB limit reached

Question 3: When Does It Occur?

**Question**: "When does this issue occur?" **Header**: "Timing" **Options**:

• **During Deployment** - wrangler deploy fails
• Description: "Error happens when deploying to Cloudflare"
• **On First Request** - First DO creation/access fails
• Description: "Error when creating new DO instance"
• **After Some Time** - Works initially, fails later
• Description: "Issue appears after DO has been running"
• **Intermittently** - Sometimes works, sometimes fails
• Description: "Inconsistent behavior, hard to reproduce"
• **Under Load** - Only happens with high traffic
• Description: "Works in testing, fails in production"

Question 4: Recent Changes

**Question**: "Have you made any recent changes to your Durable Objects configuration or code?" **Header**: "Recent Changes" **Options (multiselect)**:

• Added new DO class
• Renamed DO class
• Modified storage queries
• Changed WebSocket handling
• Updated alarms logic
• Changed package versions
• Modified wrangler.jsonc
• No recent changes

Step 2: Run Diagnostic Checks

Based on error category and context, run relevant diagnostic checks:

Check 1: Configuration Validation

Run validation script:

./scripts/validate-do-config.sh

Parse output for errors:

**Common Configuration Issues:**

1. **Missing Class Export**

   Error: Class 'MyDO' not found in src/index.ts

**Fix:**

   // src/index.ts
   export class MyDO extends DurableObject { ... }

   // Or if in separate file:
   export { MyDO } from "./MyDO";

2. **Missing Migration**

   Error: No migrations found in configuration

**Fix:**

   "migrations": [
     {
       "tag": "v1",
       "new_sqlite_classes": ["MyDO"]
     }
   ]

3. **Binding Name Mismatch**

   Error: Binding 'MY_DO' references class 'MyDO' but class not in migrations

**Fix:** Add class to migrations or update binding to match existing class.

Check 2: Code Analysis

Read DO class implementation and check for common issues:

Constructor Validation

# Find DO constructor
grep -A 20 "constructor(ctx: DurableObjectState" src/*.ts

**Common Constructor Issues:**

1. **Long-Running Constructor**

   // ❌ BAD: Heavy work in constructor (blocks all requests)
   constructor(ctx: DurableObjectState, env: Env) {
     super(ctx, env);
     await this.heavyInitialization(); // Blocks!
   }

**Fix:**

   // ✅ GOOD: Use blockConcurrencyWhile for critical initialization only
   constructor(ctx: DurableObjectState, env: Env) {
     super(ctx, env);

     this.ctx.blockConcurrencyWhile(async () => {
       // Only critical schema setup here
       await this.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS ...`);
     });
   }

2. **Missing super() Call**

   // ❌ BAD: Forgot super()
   constructor(ctx: DurableObjectState, env: Env) {
     this.ctx = ctx; // Error!
   }

**Fix:**

   // ✅ GOOD: Always call super() first
   constructor(ctx: DurableObjectState, env: Env) {
     super(ctx, env);
   }

Storage API Validation

# Find SQL queries
grep -r "storage.sql.exec" src/

**C