/cloudflare-kv:test - Test KV Namespace Connection

This command validates KV namespace configuration and tests basic operations to ensure everything is working correctly.

What This Command Does

1. Validates Configuration

   • Checks wrangler.jsonc for KV bindings
   • Verifies namespace ID format
   • Confirms binding name correctness

2. Tests CRUD Operations

   • PUT: Creates test key-value pair
   • GET: Retrieves and validates value
   • DELETE: Removes test key
   • Verifies cleanup after deletion

3. Reports Diagnostics

   • Operation success/failure status
   • Error messages with troubleshooting hints
   • Configuration recommendations

How to Use

Basic Usage

Test a specific namespace binding:

/cloudflare-kv:test MY_NAMESPACE

Replace MY_NAMESPACE with your actual binding name from wrangler.jsonc.

Interactive Mode

If no namespace provided, the command will:

1. List available namespaces from wrangler.jsonc
2. Ask which one to test
3. Run comprehensive tests

/cloudflare-kv:test

Implementation

Execute the test script from the cloudflare-kv skill:

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

The script performs:

1. Configuration validation
2. Test key generation (timestamped, unique)
3. PUT operation test
4. GET operation and value verification
5. DELETE operation test
6. Cleanup verification

Prerequisites

1. Wrangler CLI Installed

   npm install -g wrangler
   

2. Authenticated

   wrangler whoami  # Verify authentication
   

3. Namespace Configured

   • wrangler.jsonc must have kv_namespaces section
   • Namespace ID must be valid

Example Output

Successful Test

Cloudflare Workers KV - Connection Tester
==========================================

Testing namespace: MY_KV_NAMESPACE

Step 1: Checking namespace configuration...

✓ Namespace binding found in wrangler.jsonc
✓ Namespace ID: a1b2c3d4e5f6789012345678901234ab

Step 2: Testing KV operations...

Test key: __test_connection_1735300800

Testing PUT operation... ✓ Success
Testing GET operation... ✓ Success (value matches)
Testing DELETE operation... ✓ Success
Verifying deletion... ✓ Success (key removed)

Summary:
========
✓ All tests passed!

Your KV namespace 'MY_KV_NAMESPACE' is working correctly.

Failed Test

Testing namespace: BROKEN_NAMESPACE

Step 1: Checking namespace configuration...

✗ Namespace binding 'BROKEN_NAMESPACE' not found in wrangler.jsonc

Add it to your wrangler.jsonc:
  "kv_namespaces": [
    {
      "binding": "BROKEN_NAMESPACE",
      "id": "your-namespace-id"
    }
  ]

Test Scope

This command tests:

✅ Configuration

• Namespace binding exists
• Namespace ID is valid format (32 hex chars)
• wrangler.jsonc syntax is correct

✅ Operations

• PUT: Can write key-value pairs
• GET: Can retrieve values
• DELETE: Can remove keys
• Values match after write/read cycle

❌ Not Tested

• TTL/expiration (requires time delay)
• Metadata operations
• List operations
• Rate limits
• Eventual consistency across regions

For comprehensive testing, see references/troubleshooting.md.

Common Test Failures

"Namespace binding not found"

Cause: Missing or incorrect configuration

Solution:

1. Run /cloudflare-kv:setup to create namespace
2. Or manually add to wrangler.jsonc:

   "kv_namespaces": [{
     "binding": "MY_NAMESPACE",
     "id": "your-id"
   }]
   

"PUT operation failed"

Possible causes:

• Invalid namespace ID
• Authentication expired
• API rate limit reached
• Network connectivity issue

Solution:

# Re-authenticate
wrangler login

# Verify namespace ID is correct
wrangler kv namespace list

# Check wrangler.jsonc configuration
${CLAUDE_PLUGIN_ROOT}/scripts/validate-kv-config.sh

"GET value mismatch"

Cause: Eventual consistency delay

Solution: This is rare in local testing. If persistent:

1. Wait 60 seconds and retry
2. Check if namespace ID is correct
3. Verify no other processes are modifying the test key

After Testing

If tests pass:

1. Start Development

   wrangler dev
   

2. Optimize Usage

   /cloudflare-kv:optimize src/index.ts
   

3. Deploy to Production

   wrangler deploy
   

If tests fail:

1. Validate Configuration

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

2. Check Troubleshooting Guide

   • Load references/troubleshooting.md for detailed error solutions

3. Verify Account Status

   • Check Cloudflare dashboard
   • Ensure Workers plan is active
   • Verify API permissions

Related Commands

• /cloudflare-kv:setup - Create and configure new namespace
• /cloudflare-kv:optimize - Analyze KV usage patterns

References

For more details:

• Load references/troubleshooting.md for error diagnostics
• Load references/setup-guide.md for configuration help
• Check official docs: https://developers.cloudflare.com/kv/api/