Vercel KV

Last Updated: 2026-01-21 Version: @vercel/[email protected] (Redis-compatible, powered by Upstash)

---

Quick Start

# Create KV: Vercel Dashboard → Storage → KV
vercel env pull .env.local  # Creates KV_REST_API_URL and KV_REST_API_TOKEN
npm install @vercel/kv

Basic Usage:

import { kv } from '@vercel/kv';

// Set with TTL (expires in 1 hour)
await kv.setex('session:abc', 3600, { userId: 123 });

// Get
const session = await kv.get('session:abc');

// Increment counter (atomic)
const views = await kv.incr('views:post:123');

CRITICAL: Always use namespaced keys (user:123 not 123) and set TTL for temporary data.

---

Common Patterns

Caching (cache-aside):

const cached = await kv.get(`post:${slug}`);
if (cached) return cached;

const post = await db.query.posts.findFirst({ where: eq(posts.slug, slug) });
await kv.setex(`post:${slug}`, 3600, post); // Cache 1 hour
return post;

Rate Limiting:

async function checkRateLimit(ip: string): Promise<boolean> {
  const key = `ratelimit:${ip}`;
  const current = await kv.incr(key);
  if (current === 1) await kv.expire(key, 60); // 60s window
  return current <= 10; // 10 requests per window
}

Session Management:

const sessionId = crypto.randomUUID();
await kv.setex(`session:${sessionId}`, 7 * 24 * 3600, { userId });

Pipeline (batch operations):

const pipeline = kv.pipeline();
pipeline.set('user:1', data);
pipeline.incr('counter');
const results = await pipeline.exec(); // Single round-trip

Key Naming: Use namespaces like user:123, post:abc:views, ratelimit:ip:endpoint

---

Critical Rules

Always:

• ✅ Set TTL for temporary data (setex not set)
• ✅ Use namespaced keys (user:123 not 123)
• ✅ Handle null returns (non-existent keys)
• ✅ Use pipeline for batch operations

Never:

• ❌ Forget to set TTL (memory leak)
• ❌ Store large values >1MB (use Vercel Blob)
• ❌ Use KV as primary database (it's a cache)
• ❌ Store non-JSON-serializable data (functions, BigInt, circular refs)

---

Known Issues Prevention

This skill prevents 15 documented issues:

Issue #1: Missing Environment Variables

Error: Error: KV_REST_API_URL is not defined or KV_REST_API_TOKEN is not defined Source: https://vercel.com/docs/storage/vercel-kv/quickstart | GitHub Issue #759 Why It Happens: Environment variables not set locally or in deployment. In monorepos (Turborepo/pnpm workspaces), abstracting @vercel/kv into a shared package can cause Vercel builds to fail even though local builds work. Prevention: Run vercel env pull .env.local and ensure .env.local is in .gitignore. For monorepos, either (1) create client in consuming app not shared package, (2) use Vercel Environment Variables UI to set at project level, or (3) add env vars to turbo.json pipeline config: { "pipeline": { "build": { "env": ["KV_REST_API_URL", "KV_REST_API_TOKEN"] } } }.

Issue #2: JSON Serialization Error

Error: TypeError: Do not know how to serialize a BigInt or circular reference errors. Also, hset() coerces numeric strings to numbers. Source: https://github.com/vercel/storage/issues/89 | GitHub Issue #727 Why It Happens: Trying to store non-JSON-serializable data (functions, BigInt, circular refs). Additionally, when using hset() to store string values that look numeric (e.g., '123456'), hgetall() returns them as numbers, breaking type consistency. Prevention: Only store plain objects, arrays, strings, numbers, booleans, null. Convert BigInt to string. For hash fields with numeric strings, either (1) use non-numeric prefix like 'code_123456', (2) store as JSON string and parse after retrieval, or (3) validate and recast types: String(value.field) after hgetall().

Issue #3: Key Naming Collisions

Error: Unexpected data returned, data overwritten by different feature Source: Production debugging, best practices Why It Happens: Using generic key names like cache, data, temp across different features Prevention: Always use namespaced keys: feature:id:type pattern.

Issue #4: TTL Not Set

Error: Memory usage grows indefinitely, old data never expires Source: Vercel KV best practices Why It Happens: Using set() without setex() for temporary data Prevention: Use setex(key, ttl, value) for all temporary data. Set appropriate TTL (seconds).

Issue #5: Rate Limit Exceeded (Free Tier)

Error: Error: Rate limit exceeded or commands failing Source: https://vercel.com/docs/storage/vercel-kv/limits Why It Happens: Exceeding 30,000 commands/month on free tier Prevention: Monitor usage in Vercel dashboard, upgrade plan if needed, use caching to reduce KV calls.

Issue #6: Storing Large Values

Error: Error: Value too large or performance degradation Source: https://vercel.com/docs/storage/vercel-kv/limits Why It Happens: Trying to store values >1MB in KV Prevention: Use Vercel Blob for files/images. Keep KV values small (<100KB recommended).

Issue #7: Type Mismatch on Get

Error: TypeScript errors, runtime type errors. Generic kv.get<T>() sometimes returns null even when data exists. Source: Common TypeScript issue | GitHub Issue #510 Why It Happens: kv.get() returns unknown type, need to cast or validate. Additionally, there's a type inference bug where using generics like kv.get<T>() can cause the function to return null even when CLI shows data exists, due to serialization/deserialization issues. Prevention: Don't use generics with get(). Instead, retrieve without type parameter and cast after retrieval: const rawData = await kv.get('key'); const data = rawData as MyType | null;. Validate with Zod or type guards before using.

Issue #8: Pipeline Errors Not Handled

Error: Silent failures, partial execution Source: https://github.com/vercel/storage/issues/120 Why It Happens: Pipeline execution can have individual command failures Prevention: Check results array from pipeline.exec() and handle errors.

Issue #9: Scan Operation Inefficiency

Error: Slow queries, timeout errors. In v3.0.0+, cursor type changed from number to string. Source: Redis best practices | Release Notes v3.0.0 Why It Happens: Using scan() with large datasets or wrong cursor handling. Version 3.0.0 introduced a breaking change where scan cursor is now string instead of number. Prevention: Limit count parameter, iterate properly with cursor, avoid full scans in production. In v3.0.0+, use let cursor: string = "0" and compare with cursor !== "0" (not !== 0).

Issue #10: Missing TTL Refresh

Error: Session expires too early, cache invalidates prematurely Source: Production debugging Why It Happens: Not refreshing TTL on access (sliding expiration) Prevention: Use expire(key, newTTL) on access to implement sliding windows.

Issue #11: scanIterator() Infinite Loop (v2.0.0+)

Error: for await loop never terminates when using kv.scanIterator() Source: GitHub Issue #706 Why It Happens: Bug in v2.0.0+ where iterator doesn't properly signal completion. The iterator processes keys correctly but never exits, preventing the function from returning. Also affects sscanIterator(). Prevention: Use manual scan() with cursor instead of scanIterator().

// Don't use scanIterator() - it hangs in v2.0.0+
for await (const key of kv.scanIterator()) {
  // This loop never terminates
}

// Use manual scan with cursor instead
let cursor: string = "0"; // v3.x uses string
do {
  const [newCursor, keys] = await kv.scan(cursor);
  cursor = newCursor;
  for (const key of keys) {
    const value = await kv.get(key);
    // process key/value
  }
} while (cursor !== "0");

Issue #12: zrange() with rev: true Returns Empty Array

Error: kv.zrange(key, 0, -1, { rev: true }) returns empty array even though data exists Source: GitHub Issue #742 Why It Happens: SDK bug in reverse flag handling for certain key patterns. CLI always returns correct values. Removing the rev flag returns data correctly. Prevention: Omit rev flag and reverse in-memory, or use zrevrange() instead.

// This sometimes returns empty array (BUG)
const chats = await kv