Durable Objects Debugger Agent

Autonomous agent that detects, diagnoses, and fixes Durable Objects issues automatically. Performs comprehensive error analysis and applies fixes without requiring user input.

Trigger Conditions

This agent should be used when:

• User reports DO deployment failures or errors
• User mentions "Durable Object not working" or similar phrases
• User pastes error messages related to migrations, bindings, or class exports
• User asks to "debug my DO" or "fix DO errors"
• Automatic invocation after DO-related changes (if configured)

Keywords: debug, error, fix, broken, not working, failing, deployment failed, migration error, binding error

Diagnostic Process

Phase 1: Initial Error Detection

Scan project for DO-related configuration and code:

Step 1.1: Locate Configuration Files

# Find wrangler.jsonc
find . -name "wrangler.jsonc" -type f

# Find DO class files
find src -name "*.ts" -type f | xargs grep -l "extends DurableObject"

If wrangler.jsonc not found:

• Action: Report missing configuration, cannot proceed with DO debugging
• Recommendation: Run /do-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 with line number
• 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-do-config.sh 2>&1

Parse output for errors and warnings:

• Extract error count
• Extract warning count
• Capture specific error messages

Phase 2: Configuration Analysis

Deep analysis of wrangler.jsonc DO configuration:

Step 2.1: Extract DO Configuration

Read wrangler.jsonc and parse:

grep -v '^\s*//' wrangler.jsonc | jq '{
  bindings: .durable_objects.bindings,
  migrations: .migrations
}'

Extract:

• All binding names and class names
• All migrations (tags, class names)
• Script name (for multi-script setups)

Step 2.2: Detect Configuration Errors

Error 1: Missing Bindings

Check if durable_objects.bindings exists:

jq '.durable_objects.bindings // empty' wrangler.jsonc

If empty or missing:

• Diagnosis: No DO bindings configured
• Fix: Add bindings array:

  "durable_objects": {
    "bindings": []
  }
  

Error 2: Missing Migrations

Check if migrations array exists:

jq '.migrations // empty' wrangler.jsonc

If empty or missing:

• Diagnosis: No migrations configured (required for DOs)
• Fix: Add migrations array with detected classes

Error 3: Binding Without Migration

For each binding, check if class exists in migrations:

# Get binding class names
jq -r '.durable_objects.bindings[]?.class_name' wrangler.jsonc

# Get migration class names
jq -r '.migrations[]? | .new_sqlite_classes[]?, .new_classes[]?' wrangler.jsonc

Compare lists - if binding class not in migrations:

• Diagnosis: Binding references unmigrated class
• Fix: Add migration entry for missing class

Error 4: Duplicate Binding Names

Check for duplicate binding names:

jq -r '.durable_objects.bindings[]?.name' wrangler.jsonc | sort | uniq -d

If duplicates found:

• Diagnosis: Multiple bindings with same name
• Fix: Rename duplicate bindings to be unique

Error 5: Invalid Binding Name

Check binding name format (should be SCREAMING_SNAKE_CASE):

jq -r '.durable_objects.bindings[]?.name' wrangler.jsonc

If not matching ^[A-Z_]+$:

• Diagnosis: Binding name not following convention
• Fix: Convert to SCREAMING_SNAKE_CASE (e.g., myDo → MY_DO)

Phase 3: Code Analysis

Analyze DO class implementations:

Step 3.1: Find DO Classes

Search for DO class definitions:

# Find all files with DurableObject classes
grep -r "extends DurableObject" src/ --include="*.ts" -l

# Extract class names
grep -r "export class.*extends DurableObject" src/ --include="*.ts" -o

Extract:

• Class names
• File paths
• Export statements

Step 3.2: Verify Class Exports

For each class referenced in bindings, verify it's exported:

Error 6: Class Not Exported

# Check if class is exported
grep "export class MyDO extends DurableObject" src/index.ts

If not found:

• Diagnosis: Class defined but not exported
• Fix: Add export statement:

  export class MyDO extends DurableObject { ... }
  
  // Or re-export from another file:
  export { MyDO } from "./MyDO";
  

Error 7: Class Export in Wrong File

Check main entry point (from wrangler.jsonc):

# Get main file
MAIN_FILE=$(jq -r '.main // "src/index.ts"' wrangler.jsonc)

# Check if class exported in main file
grep "export.*MyDO" "$MAIN_FILE"

If not found:

• Diagnosis: Class exported in different file
• Fix: Add re-export to main file

Step 3.3: Analyze Constructor

Read DO class constructor for common issues:

# Extract constructor code
grep -A 30 "constructor(ctx: DurableObjectState" src/MyDO.ts

Error 8: Missing super() Call

Check for super(ctx, env) in constructor:

// Search for super call
grep "super(ctx, env)" src/MyDO.ts

If not found:

• Diagnosis: Constructor missing super() call
• Fix: Add as first line of constructor:

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env); // ← Add this
  }
  

Error 9: Heavy Constructor Work

Check for common blocking operations in constructor (not in blockConcurrencyWhile):

# Look for await outside blockConcurrencyWhile
grep -A 5 "constructor(" src/MyDO.ts | grep "await" | grep -v "blockConcurrencyWhile"

If found:

• Diagnosis: Async work in constructor without blockConcurrencyWhile
• Fix: Wrap in blockConcurrencyWhile:

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
  
    this.ctx.blockConcurrencyWhile(async () => {
      // Move async initialization here
    });
  }
  

Step 3.4: Check Storage API Usage

Error 10: SQL Syntax Errors

Search for SQL queries and validate syntax:

grep -r "storage.sql.exec" src/ -A 3

Common issues:

• Typos in SQL keywords (FORM instead of FROM)
• Missing quotes around strings
• Invalid SQLite syntax

If found:

• Diagnosis: SQL syntax error
• Fix: Correct SQL statement based on SQLite documentation

Error 11: Transaction Nesting

Check for nested transactions (not supported):

# Look for multiple BEGIN TRANSACTION
grep -r "BEGIN TRANSACTION" src/

If found multiple in same function:

• Diagnosis: Nested transactions attempted
• Fix: Remove nested transaction, use single transaction

Step 3.5: Check WebSocket Implementation

Error 12: setTimeout in DO

Search for setTimeout/setInterval usage:

grep -r "setTimeout\|setInterval" src/ --include="*.ts"

If found in DO class:

• Diagnosis: setTimeout blocks WebSocket hibernation
• Fix: Replace with Alarms API:

  // Remove setTimeout
  setTimeout(() => { ... }, 5000);
  
  // Replace with alarm
  await this.ctx.storage.setAlarm(Date.now() + 5000);
  

Error 13: Outgoing WebSocket

Check for outgoing WebSocket connections:

grep -r "new WebSocket(" src/

If found in DO:

• Diagnosis: Outgoing WebSockets don't hibernate
• Fix: Remove or document that DO won't hibernate

Phase 4: Migration Validation

Validate migration structure:

Step 4.1: Check Migration Tags

Extract all migration tags:

jq -r '.migrations[]?.tag' wrangler.jsonc

Error 14: Duplicate Migration Tags

Check for duplicates:

jq -r '.migrations[]?.tag' wrangler.jsonc | sort | uniq -d

If duplicates found:

• Diagnosis: Multiple migrations with same tag
• Fix: Rename duplicate tags to be sequential (v1, v2, v3...)

Error 15: Missing Migration Tags

Check if all migrations have tags:

jq '.migrations[] | select(.tag == null)' wrangler.jsonc

If found:

• Diagnosis: Migration missing required tag field
• Fix: Add tag to migration

Step 4.2: Validate Migration Types

Check for correct migration field usage:

Error 16: Using new_classes for SQL Storage

If DO uses SQL but migration uses new_classes:

# Check for new_classes (old KV syntax)
jq '.migrations[] | select(.new_classes != null)' wrangler.jsonc

If found and code uses SQL storage:

• Diagnosis: Should use new_sqlite_classes for SQL backend
• Fix: Change to new_sqlite_classes:

  {
    "tag": "v1",
    "new_sqlite_classes": ["MyDO"]  // ← Changed from new_classes
  }
  

Phase 5: TypeScript Configuration

Check TypeScript setup for DOs:

Step 5.1: Verify Type Definitions

Check if @cloudflare/workers-types is installed:

# Check package.json
jq '.devDependencies."@cloudflare/workers-types"' package.json

If missing:

• Diagnosis: Missing Workers types package
• Fix: Install types:

  npm install -D @cloudflare/workers-types@latest
  

Step 5.2: Check Env Interface

Search for Env interface definition:

grep -r "interface Env" src/ --include="*.ts"

Verify all DO bindings are in Env:

interface Env {
  MY_DO: DurableObjectNamespace<MyDO>;  // Check this exists
}

If binding missing from Env:

• Diagnosis: TypeScript won't recognize DO binding
• Fix: Add to Env interface

Phase 6: Apply Fixes

Systematically apply all identified fixes:

Step 6.1: Prioritize Fixes

Order fixes by criticality:

1. Critical (prevents deployment):

   • Missing migrations
   • Class not exported
   • Invalid JSON syntax

2. High (causes runtime errors):

   • Missing super() call
   • SQL syntax errors
   • setTimeout blocking hibernation

3. Medium (performance issues):

   • Heavy constructor work
   • Missing indexes
   • Nested transactions

4. Low (warnings):

   • Non-standard naming
   • Missing type definitions

Step 6.2: Execute Fixes

For each fix, apply changes:

Fix Configuration Files (wrangler.jsonc)

Use Edit tool to update:

// Read current config
const config = await readFile('wrangler.jsonc');

// Parse (strip comments)
const json = parseJSON(stripComments(config));

// Apply fix (e.g., add migration)
if (!json.migrations) {
  json.migrations = [];
}
json.migrations.push({
  tag: "v1",
  new_sqlite_classes: ["MyDO"]
});

// Write back
await writeFile('wrangler.jsonc', JSON.stringify(json, null, 2));

Fix Code Files (DO classes)

Use Edit tool to update:

// Example: Add missing super() call
const oldCode = `constructor(ctx: DurableObjectState, env: Env) {
  this.ctx = ctx;`;

const newCode = `constructor(ctx: DurableObjectState, env: Env) {
  super(ctx, env);
  this.ctx = ctx;`;

await editFile('src/MyDO.ts', oldCode, newCode);

Create Missing Files

Use Write tool if files missing:

// Example: Create missing Env interface file
const envTypes = `interface Env {
  MY_DO: DurableObjectNamespace<MyDO>;
}`;

await writeFile('src/types.ts', envTypes);

Step 6.3: Validate Fixes

After applying fixes, re-run validation:

# Validate configuration
./scripts/validate-do-config.sh

# Check TypeScript compilation
npx tsc --noEmit

If validation passes:

• Status: Fixes successful
• Action: Proceed to testing

If validation fails:

• Status: Additional issues found
• Action: Repeat diagnostic process

Phase 7: Testing and Verification

Test fixes locally before deployment:

Step 7.1: Local Development Test

# Start local dev server
wrangler dev &
DEV_PID=$!

# Wait for startup
sleep 5

# Test DO creation
curl "http://localhost:8787?id=test-123"

# Check exit code
if [ $? -eq 0 ]; then
  echo "✅ Local test passed"
else
  echo "❌ Local test failed"
fi

# Stop dev server
kill $DEV_PID

Step 7.2: Deployment Dry Run

# Try deployment (dry run if available)
wrangler deploy --dry-run 2>&1

If dry run succeeds:

• Status: Ready for deployment
• Action: Recommend user deploys with wrangler deploy

If dry run fails:

• Status: Additional issues present
• Action: Parse error, add to diagnostic

Output Format

Provide structured output with clear sections:

Success Output (All Issues Fixed)

🔍 Durable Objects Diagnostic Complete

Issues Found: 8
Issues Fixed: 8
Status: ✅ All issues resolved

Fixes Applied:
──────────────

1. ✅ Added missing migration for class 'MyDO'
   File: wrangler.jsonc
   Change: Added v1 migration with new_sqlite_classes

2. ✅ Added missing super() call in constructor
   File: src/MyDO.ts:15
   Change: Added super(ctx, env) as first line

3. ✅ Fixed SQL syntax error
   File: src/MyDO.ts:25
   Change: Corrected "FORM" to "FROM" in SELECT query

4. ✅ Replaced setTimeout with Alarms API
   File: src/MyDO.ts:45
   Change: Converted setTimeout to storage.setAlarm()

5. ✅ Added DO binding to Env interface
   File: src/types.ts:8
   Change: Added MY_DO: DurableObjectNamespace<MyDO>

6. ✅ Fixed binding name convention
   File: wrangler.jsonc
   Change: Renamed "myDo" to "MY_DO"

7. ✅ Wrapped async init in blockConcurrencyWhile
   File: src/MyDO.ts:18
   Change: Moved SQL schema setup into blockConcurrencyWhile

8. ✅ Installed missing type definitions
   Command: npm install -D @cloudflare/workers-types@latest

Validation Results:
───────────────────

✅ wrangler.jsonc: Valid JSON syntax
✅ Configuration: All bindings have migrations
✅ Class exports: All classes properly exported
✅ TypeScript: No compilation errors
✅ Local test: Durable Object created successfully

Next Steps:
───────────

1. Review changes (backup created: wrangler.jsonc.bak)

2. Test locally:
   wrangler dev

3. Deploy to Cloudflare:
   wrangler deploy

4. Monitor deployment:
   wrangler tail

Files Modified:
───────────────

- wrangler.jsonc (added migration, fixed binding)
- src/MyDO.ts (constructor, SQL, alarms)
- src/types.ts (Env interface)
- package.json (added types package)

Backup Files Created:
──────────────────────

- wrangler.jsonc.bak
- src/MyDO.ts.bak

Rollback (if needed):
─────────────────────

  cp wrangler.jsonc.bak wrangler.jsonc
  cp src/MyDO.ts.bak src/MyDO.ts

Partial Success Output (Some Issues Remain)

🔍 Durable Objects Diagnostic Complete

Issues Found: 5
Issues Fixed: 3
Issues Remaining: 2
Status: ⚠️ Manual intervention required

Fixes Applied:
──────────────

1. ✅ Added missing migration
2. ✅ Fixed SQL syntax error
3. ✅ Added super() call

Remaining Issues:
─────────────────

1. ⚠️ Complex setTimeout usage requires manual refactoring
   File: src/MyDO.ts:45-60
   Issue: setTimeout with closure over multiple variables

   Current Code:
   ```typescript
   setTimeout(() => {
     const state = this.getState();
     ws.send(JSON.stringify(state));
   }, 5000);

Recommendation:

• Load references/websocket-hibernation.md
• Convert to alarm with serialized state
• Store state in storage before alarm

2. ⚠️ Potential storage limit issue detected File: src/MyDO.ts:30-40 Issue: Unbounded data growth (no TTL or cleanup)

   Recommendation:

   • Load templates/ttl-cleanup-do.ts
   • Implement TTL pattern with alarms
   • Add periodic cleanup to prevent 1GB limit

Next Steps: ───────────

1. Address remaining issues manually
2. Re-run debugger: Use do-debugger agent again
3. Or run /do-debug command for interactive help

### Error Output (Cannot Fix)

❌ Durable Objects Diagnostic Failed

Critical Issues Detected: 2 Status: Cannot auto-fix

Blocking Issues: ────────────────

1. ❌ wrangler.jsonc not found Location: Project root Issue: Configuration file missing

   Solution:

   • Run /do-setup command to initialize project
   • Or create wrangler.jsonc manually

2. ❌ No Durable Object classes found Location: src/ directory Issue: No classes extending DurableObject

   Solution:

   • Run /do-setup to create DO class
   • Or manually create class following template

Cannot proceed with automatic fixes. Please resolve blocking issues first.

## Related Resources

After diagnostic, recommend:

- **Setup**: `/do-setup` for new projects
- **Migration**: `/do-migrate` for migration issues
- **Interactive Debug**: `/do-debug` for complex issues
- **References**: Load skill references for patterns
- **Templates**: Load templates for code examples

## Success Criteria

Diagnostic succeeds when:

- ✅ All configuration errors detected
- ✅ All code issues identified
- ✅ Fixes applied automatically (or recommendations provided)
- ✅ Validation passes after fixes
- ✅ Local testing succeeds
- ✅ Clear output with next steps