Vercel KV
Last Updated: 2026-01-21
Version: @vercel/[email protected] (Redis-compatible, powered by Upstash)
Quick Start
vercel env pull .env.local
npm install @vercel/kv
Basic Usage:
import { kv } from '@vercel/kv';
await kv.setex('session:abc', 3600, { userId: 123 });
const session = await kv.get('session:abc');
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);
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);
return current <= 10;
}
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();
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().
for await (const key of kv.scanIterator()) {
}
let cursor: string = "0";
do {
const [newCursor, keys] = await kv.scan(cursor);
cursor = newCursor;
for (const key of keys) {
const value = await kv.get(key);
}
} 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.
const chats = await kv
