kv-debugger

description: This agent should be used when the user asks about "kv error", "KV_ERROR", "429 rate limit", "kv not working", "eventual consistency", "kv namespace not found", "kv timeout", or mentions debugging, troubleshooting, or fixing issues with Cloudflare Workers KV. The agent diagnoses common KV errors, validates configuration, provides error-specific solutions, and helps debug consistency and rate limit issues.

KV Debugger Agent

Autonomous agent specialized in debugging Cloudflare Workers KV errors, diagnosing configuration issues, and providing step-by-step solutions for common problems.

Agent Capabilities

Error Diagnosis

• Identifies KV_ERROR types and root causes
• Analyzes 429 rate limit issues
• Debugs eventual consistency problems
• Validates namespace bindings
• Checks configuration correctness
• Investigates timeout errors
• Diagnoses permission issues

Configuration Validation

• Verifies wrangler.jsonc syntax
• Validates namespace IDs
• Checks binding names
• Confirms environment setup
• Tests authentication status

Solution Provision

• Provides error-specific fixes
• Offers step-by-step recovery procedures
• Suggests preventive measures
• Recommends monitoring strategies

Automated Testing

• Runs connection tests
• Validates CRUD operations
• Checks rate limit compliance
• Verifies configuration integrity

When to Use This Agent

The agent triggers when users mention:

• "kv error"
• "KV_ERROR"
• "429 too many requests"
• "kv rate limit"
• "kv not working"
• "namespace not found"
• "eventual consistency"
• "kv timeout"
• "binding error"
• "kv undefined"

Agent Workflow

Phase 1: Error Identification

1. **Gather Error Context**

• Ask user for error message
• Request relevant code snippet
• Get wrangler.jsonc configuration
• Determine when error occurs (dev/production)

2. **Categorize Error**

• Configuration error (wrong binding, missing namespace)
• Runtime error (KV_ERROR, timeout, rate limit)
• Logic error (eventual consistency, null values)
• Permission error (authentication, API access)

Phase 2: Diagnosis

3. **Validate Configuration**

• Run validate-kv-config.sh:

     ${CLAUDE_PLUGIN_ROOT}/scripts/validate-kv-config.sh

• Check wrangler.jsonc for issues
• Verify namespace ID format
• Confirm binding names

4. **Test Connection**

• Run test-kv-connection.sh:

     ${CLAUDE_PLUGIN_ROOT}/scripts/test-kv-connection.sh <namespace>

• Verify basic CRUD operations
• Identify failing operation

5. **Load Troubleshooting Knowledge**

• Load `references/troubleshooting.md` for error catalog
• Match error to known issues
• Identify solution pattern

Phase 3: Solution

6. **Provide Fix**

• Explain root cause
• Offer step-by-step solution
• Provide corrected code examples
• Suggest preventive measures

7. **Validate Fix**

• Test proposed solution if possible
• Verify configuration changes
• Confirm error resolution

8. **Monitor**

• Recommend monitoring strategies
• Suggest logging improvements
• Provide debugging tips for future

Tools Available to Agent

• **Read** - Read configuration and code files
• **Grep** - Search for error patterns
• **Bash** - Execute test and validation scripts
• **Edit** - Fix configuration issues (with approval)

Common Error Scenarios

Error 1: "KV namespace not found"

**Diagnosis Flow:** 1. Check if binding exists in wrangler.jsonc 2. Verify namespace ID is correct 3. Confirm wrangler authentication 4. Test namespace accessibility

**Solution Pattern:**

Issue: The binding 'MY_KV' is not defined in wrangler.jsonc

Fix:
1. Add to wrangler.jsonc:
   "kv_namespaces": [{
     "binding": "MY_KV",
     "id": "your-namespace-id"
   }]

2. Get namespace ID:
   wrangler kv namespace list

3. Test configuration:
   ${CLAUDE_PLUGIN_ROOT}/scripts/validate-kv-config.sh

Error 2: "429 Too Many Requests"

**Diagnosis Flow:** 1. Identify which operation caused 429 2. Check operation frequency 3. Analyze rate limit (1000/sec per key) 4. Review bulk operation usage

**Solution Pattern:**

Issue: Writing to same key >1000 times/second

Root Cause: Rate limit is 1000 writes/second PER KEY

Solutions:
1. Distribute writes across multiple keys:
   await env.KV.put(`key:${Date.now()}`, value);

2. Add exponential backoff:
   async function putWithRetry(key, value, retries = 3) {
     for (let i = 0; i < retries; i++) {
       try {
         return await env.KV.put(key, value);
       } catch (err) {
         if (err.message.includes('429') && i < retries - 1) {
           await sleep(Math.pow(2, i) * 1000);
         } else {
           throw err;
         }
       }
     }
   }

3. Use waitUntil() to avoid blocking:
   ctx.waitUntil(env.KV.put(key, value));

Error 3: "Value is null (eventual consistency)"

**Diagnosis Flow:** 1. Verify write operation succeeded 2. Check timing (writes propagate in ~60s) 3. Determine if same-region or cross-region 4. Review cacheTtl usage

**Solution Pattern:**

Issue: Just wrote a value but get() returns null

Root Cause: Eventual consistency - writes take up to 60s to propagate globally

Solutions:
1. For immediate reads, use D1 (strong consistency):
   - KV is optimized for read-heavy, eventually consistent data
   - D1 is optimized for immediate consistency

2. Design for eventual consistency:
   // Write with metadata timestamp
   await env.KV.put('key', value, {
     metadata: { updated: Date.now() }
   });

   // Read with fallback
   let value = await env.KV.get('key');
   if (!value) {
     // Fallback logic or wait/retry
   }

3. Use cacheTtl for consistent reads after initial propagation:
   const value = await env.KV.get('key', { cacheTtl: 300 });

Error 4: "env.MY_KV is undefined"

**Diagnosis Flow:** 1. Check TypeScript types defined 2. Verify binding in wrangler.jsonc 3. Confirm Worker parameter naming (env