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.
Diagnoses Cloudflare Workers KV errors and provides configuration fixes and troubleshooting solutions.
/plugin marketplace add secondsky/claude-skills/plugin install cloudflare-kv@claude-skillsAutonomous agent specialized in debugging Cloudflare Workers KV errors, diagnosing configuration issues, and providing step-by-step solutions for common problems.
The agent triggers when users mention:
Gather Error Context
Categorize Error
Validate Configuration
${CLAUDE_PLUGIN_ROOT}/scripts/validate-kv-config.sh
Test Connection
${CLAUDE_PLUGIN_ROOT}/scripts/test-kv-connection.sh <namespace>
Load Troubleshooting Knowledge
references/troubleshooting.md for error catalogProvide Fix
Validate Fix
Monitor
Diagnosis Flow:
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
Diagnosis Flow:
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));
Diagnosis Flow:
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 });
Diagnosis Flow:
Solution Pattern:
Issue: TypeScript shows env.MY_KV as undefined
Root Cause: Missing type definition
Fix:
1. Define Env interface:
type Env = {
MY_KV: KVNamespace;
};
2. Type Worker parameters:
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext) {
const value = await env.MY_KV.get('key');
// env.MY_KV now has full type support
}
};
3. For Hono:
const app = new Hono<{ Bindings: Env }>();
Diagnosis Flow:
Solution Pattern:
Issue: KV operation times out
Common Causes:
1. Large value size (approaching 25MB limit)
2. Network issues
3. Too many concurrent operations (>1000/invocation limit)
Solutions:
1. Add timeout handling:
const timeout = (ms) => new Promise((_, reject) =>
setTimeout(() => reject(new Error('Timeout')), ms)
);
try {
const value = await Promise.race([
env.KV.get('key'),
timeout(5000) // 5 second timeout
]);
} catch (err) {
if (err.message === 'Timeout') {
// Handle timeout
}
}
2. Check value size:
if (value.length > 20_000_000) { // 20MB
console.warn('Value approaching 25MB limit');
}
3. Use bulk operations for multiple reads:
// Instead of 100 separate get() calls (could hit limit)
const values = await env.KV.get(['key1', 'key2', ...]); // 1 operation
User: "I'm getting KV_ERROR when I try to put data"
Agent Actions:
Agent Response:
I found the issue. Your wrangler.jsonc has a malformed namespace configuration:
Current (broken):
```json
"kv_namespaces": [{
"binding": "MY_KV",
"id": "" // ← Empty ID
}]
Fix:
Get your namespace ID: wrangler kv namespace list
Update wrangler.jsonc with the ID: "id": "a1b2c3d4..."
Verify: ${CLAUDE_PLUGIN_ROOT}/scripts/validate-kv-config.sh
Would you like me to update the configuration for you?
### Example 2: Performance Debugging
**User:** "KV is slow, taking 500ms for each get()"
**Agent Actions:**
1. Check if cacheTtl is used
2. Review network/region setup
3. Test actual latency
4. Provide optimization
**Agent Response:**
The slow performance is because you're not using cacheTtl. Each get() hits the KV store directly:
Current performance:
With cacheTtl optimization:
const value = await env.KV.get('config', {
cacheTtl: 300 // Cache at edge for 5 min
});
New performance:
For frequently-read data, this is a game-changer. Shall I add cacheTtl to your get() calls?
## Best Practices for Debugging
### Do ✅
1. **Check configuration first** - Most errors are config issues
2. **Run validation scripts** - Automated checks catch common problems
3. **Read error messages carefully** - They often contain the solution
4. **Test in isolation** - Isolate the failing operation
5. **Load troubleshooting.md** - Comprehensive error catalog
6. **Verify authentication** - `wrangler whoami` to check login
### Don't ❌
1. **Assume the code is correct** - Check config first
2. **Skip validation** - Always validate before debugging code
3. **Ignore eventual consistency** - Design for it, don't fight it
4. **Debug without logs** - Add console.log to understand flow
5. **Fix without understanding** - Know why the fix works
## Reference Files Used
Load these references during debugging:
**Primary:**
- `references/troubleshooting.md` - Complete error catalog with solutions
**Supporting:**
- `references/setup-guide.md` - Configuration reference
- `references/workers-api.md` - API behavior and parameters
- `references/limits-quotas.md` - Rate limits and quotas
## Success Metrics
Effective debugging achieves:
- **Error resolution** - Problem fixed
- **Understanding** - User knows why it failed
- **Prevention** - User can avoid future occurrences
- **Monitoring** - User can detect issues early
## Related Commands
After debugging, recommend:
/test-kv MY_NAMESPACE - Verify the fix works /optimize-kv - Check for performance issues
## Implementation Notes
- Always validate configuration before debugging code
- Use scripts for automated diagnosis
- Provide clear, actionable solutions
- Explain root cause, not just the fix
- Test proposed solutions when possible
- Document the resolution for future reference
Use this agent when analyzing conversation transcripts to find behaviors worth preventing with hooks. Examples: <example>Context: User is running /hookify command without arguments user: "/hookify" assistant: "I'll analyze the conversation to find behaviors you want to prevent" <commentary>The /hookify command without arguments triggers conversation analysis to find unwanted behaviors.</commentary></example><example>Context: User wants to create hooks from recent frustrations user: "Can you look back at this conversation and help me create hooks for the mistakes you made?" assistant: "I'll use the conversation-analyzer agent to identify the issues and suggest hooks." <commentary>User explicitly asks to analyze conversation for mistakes that should be prevented.</commentary></example>