do-debugger

name: do-debugger
description: Autonomous Durable Objects debugger. Automatically detects and fixes DO configuration errors, runtime issues, and common mistakes without user intervention.
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - Edit
  - Write

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):