use cache: private doesn't work in route handlers

[ellemedit]

Summary

both use cache and use cache: remote work in route handler but use cache: private doesn't work in route handler. it doesn't dedupe invocations and memoization during a request.

Additional information

I tested in local development.

RSC works:

import { cacheLife, cacheTag } from "next/cache";
import { headers } from "next/headers";
import { Suspense } from "react";

let cacheValue = 0;

async function getCachePrivateValue() {
  "use cache: private";
  cacheTag("test-private");
  cacheLife({ stale: 60 });
  
  const auth = (await headers()).get('Authorization') || 'guest';
  console.log('Called:', auth, cacheValue);
  cacheValue += 1;
  return cacheValue;
}

export default async function TestCachePage() {
  const results = [];
  for (let i = 0; i < 11; i++) {
    results.push(getCachePrivateValue());
  }
  
  return (
    <div>
      <h1>Cache Test</h1>
      <Suspense>
        {Promise.all(results).then(results => results.join(", "))}
      </Suspense>
    </div>
  );
}

it prints [1, 1, 1, ..., 1] or [2, 2, 2, ..., 2] at the same time.

but route handler doesn't:

import { cacheLife, cacheTag } from "next/cache";

export async function GET() {
  for (let i = 0; i < 10; i++) {
    await getCachePrivateValue(1);
  }
  const count = await getCachePrivateValue(1);
  return Response.json({ count });
}

let cacheValue = 0;

export async function getCachePrivateValue(id: number) {
  "use cache: private";
  cacheTag(`useCachePrivateCheck-${id}`);
  cacheLife({ stale: 60, revalidate: 60, expire: Infinity });
  cacheValue += 1;
  return cacheValue;
}

it prints 11, 22 or 33

all tests were validated at [email protected] canary

[Raunakg2005]

Hi @ellemedit! Great catch on this behavior difference. The issue you're experiencing with use cache: private in Route Handlers is expected behavior in Next.js 15/16 due to how the caching directives work in different contexts.

🔍 Why It Doesn't Work in Route Handlers

Route Handlers vs React Server Components

The key difference:

• RSC (React Server Components): Runs during React's render phase, supports request-scoped memoization
• Route Handlers: Run independently, don't participate in React's render lifecycle

use cache: private is specifically designed for request-scoped deduplication within the React rendering tree. Route handlers don't have this context, so the private cache behaves like no cache at all.

---

✅ Solutions for Route Handlers

Solution 1: Use unstable_cache Instead (Recommended)

For Route Handlers, use Next.js's unstable_cache which works correctly:

import { unstable_cache } from 'next/cache'
import { cacheTag } from 'next/cache'

export async function GET() {
  const cachedFunction = unstable_cache(
    async (id: number) => {
      let cacheValue = 0
      cacheValue += 1
      return cacheValue
    },
    ['cache-private-check'], // Cache key
    {
      tags: ['useCachePrivateCheck-1'],
      revalidate: 60,
    }
  )

  // This will properly dedupe
  for (let i = 0; i < 10; i++) {
    await cachedFunction(1)
  }
  
  const count = await cachedFunction(1)
  return Response.json({ count }) // Will return 1, not 11
}

Solution 2: Manual Request-Scoped Cache with AsyncLocalStorage

If you need request-scoped caching similar to use cache: private:

import { cache } from 'react'

// Define your cached function
const getCachePrivateValue = cache(async (id: number) => {
  let cacheValue = 0
  cacheValue += 1
  console.log('Called for id:', id, 'value:', cacheValue)
  return cacheValue
})

export async function GET() {
  // All calls within this request will be deduped
  for (let i = 0; i < 10; i++) {
    await getCachePrivateValue(1)
  }
  
  const count = await getCachePrivateValue(1)
  return Response.json({ count }) // Will return 1
}

Solution 3: Use In-Memory Map for Request Deduplication

For more control over caching within a single request:

import { cacheLife, cacheTag } from "next/cache"

const requestCache = new Map<string, Promise<any>>()

export async function GET(request: Request) {
  const requestId = request.headers.get('x-request-id') || Date.now().toString()
  
  async function getCachedValue(id: number) {
    const key = `${requestId}-${id}`
    
    if (requestCache.has(key)) {
      return requestCache.get(key)
    }
    
    const promise = (async () => {
      let cacheValue = 0
      cacheValue += 1
      return cacheValue
    })()
    
    requestCache.set(key, promise)
    
    // Clean up after request
    setTimeout(() => requestCache.delete(key), 1000)
    
    return promise
  }

  for (let i = 0; i < 10; i++) {
    await getCachedValue(1)
  }
  
  const count = await getCachedValue(1)
  return Response.json({ count }) // Will return 1
}

---

📊 Comparison: What Works Where

Cache Type	RSC Components	Route Handlers	Use Case
use cache	✅ Yes	⚠️ Limited	Global caching
use cache: remote	✅ Yes	✅ Yes	Distributed cache
use cache: private	✅ Yes	❌ No	Request-scoped (React only)
unstable_cache	✅ Yes	✅ Yes	Data Cache API
cache() from React	✅ Yes	✅ Yes	Request deduplication

---

🎯 Why This Happens

From the Next.js caching architecture:

1. use cache: private relies on React's request context (AsyncLocalStorage)
2. Route Handlers run outside React's render tree
3. The "private" cache scope needs the React rendering context to track the request boundary
4. Without this context, each call is treated as a new request

---

🔧 Recommended Pattern for Your Use Case

Based on your code, here's the best approach:

// app/api/your-route/route.ts
import { unstable_cache } from 'next/cache'
import { cacheLife, cacheTag } from 'next/cache'

export async function GET() {
  // Define cached function
  const getCachedValue = unstable_cache(
    async (id: number) => {
      console.log('Cache miss for id:', id)
      // Your expensive operation here
      return performExpensiveOperation(id)
    },
    ['cache-private-value'], // Unique cache key
    {
      tags: ['useCachePrivateCheck'],
      revalidate: 60,
    }
  )

  // This will properly cache and dedupe
  for (let i = 0; i < 10; i++) {
    await getCachedValue(1) // Only called once
  }
  
  const count = await getCachedValue(1)
  return Response.json({ count })
}

async function performExpensiveOperation(id: number) {
  // Your logic here
  return id
}

---

📚 Additional Resources

• Next.js Caching Deep Dive
• unstable_cache API Reference
• React cache() Documentation
• Next.js 15 Caching Improvements

---

🤔 Is This a Bug?

No, this is expected behavior. The use cache: private directive is specifically for React Server Components, not Route Handlers. For Route Handlers, use unstable_cache or React's cache().

If you believe Route Handlers should support use cache: private, you could open a feature request on the Next.js GitHub repo explaining your use case!

Hope this helps clarify the behavior! Let me know if you need help implementing any of these solutions. 🚀