vercel · Copilot · Sep 12, 2025 · Sep 12, 2025 · Sep 12, 2025 · Sep 19, 2025
diff --git a/examples/cache-handler-redis/cache-handler.js b/examples/cache-handler-redis/cache-handler.js
@@ -19,7 +19,12 @@ CacheHandler.onCreation(async () => {
       // NB do not throw exceptions in the redis error listener,
       // because it will prevent reconnection after a socket exception.
       client.on("error", (e) => {
-        if (typeof process.env.NEXT_PRIVATE_DEBUG_CACHE !== "undefined") {
+        // Check if debug logging is enabled with proper truthy value check
+        const debugValue = process.env.NEXT_PRIVATE_DEBUG_CACHE
+        const isDebugEnabled = debugValue && 
+          ['1', 'true', 'yes'].includes(debugValue.toLowerCase().trim())
+
+        if (isDebugEnabled) {
           console.warn("Redis error", e);
         }
       });

diff --git a/packages/next/src/server/app-render/app-render.tsx b/packages/next/src/server/app-render/app-render.tsx
@@ -1,3 +1,4 @@
+import { isDebugCacheEnabled } from '../lib/debug-utils'
 import type { RenderOpts, PreloadCallbacks } from './types'
 import type {
   ActionResult,
@@ -1798,7 +1799,7 @@ async function renderToHTMLOrFlightImpl(
       workStore.pendingRevalidatedTags
     ) {
       const pendingPromise = executeRevalidates(workStore).finally(() => {
-        if (process.env.NEXT_PRIVATE_DEBUG_CACHE) {
+        if (isDebugCacheEnabled()) {
           console.log('pending revalidates promise finished for:', url)
         }
       })
@@ -1966,7 +1967,7 @@ async function renderToHTMLOrFlightImpl(
       workStore.pendingRevalidatedTags
     ) {
       const pendingPromise = executeRevalidates(workStore).finally(() => {
-        if (process.env.NEXT_PRIVATE_DEBUG_CACHE) {
+        if (isDebugCacheEnabled()) {
           console.log('pending revalidates promise finished for:', url)
         }
       })

diff --git a/packages/next/src/server/lib/cache-handlers/default.external.ts b/packages/next/src/server/lib/cache-handlers/default.external.ts
@@ -7,6 +7,7 @@
  * considered expired/missing in such cache handlers.
  */
 
+import { isDebugCacheEnabled } from '../debug-utils'
 import { LRUCache } from '../lru-cache'
 import type { CacheEntry, CacheHandlerV2 } from './types'
 import {
@@ -41,7 +42,7 @@ const memoryCache = new LRUCache<PrivateCacheEntry>(
 )
 const pendingSets = new Map<string, Promise<void>>()
 
-const debug = process.env.NEXT_PRIVATE_DEBUG_CACHE
+const debug = isDebugCacheEnabled()
   ? console.debug.bind(console, 'DefaultCacheHandler:')
   : undefined
 

diff --git a/packages/next/src/server/lib/debug-utils.test.ts b/packages/next/src/server/lib/debug-utils.test.ts
@@ -0,0 +1,91 @@
+import { isDebugCacheEnabled } from './debug-utils'
+
+describe('isDebugCacheEnabled', () => {
+  const originalEnv = process.env.NEXT_PRIVATE_DEBUG_CACHE
+
+  afterEach(() => {
+    // Restore original value
+    if (originalEnv === undefined) {
+      delete process.env.NEXT_PRIVATE_DEBUG_CACHE
+    } else {
+      process.env.NEXT_PRIVATE_DEBUG_CACHE = originalEnv
+    }
+  })
+
+  it('should return true for "1"', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = '1'
+    expect(isDebugCacheEnabled()).toBe(true)
+  })
+
+  it('should return true for "true" (case-insensitive)', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'true'
+    expect(isDebugCacheEnabled()).toBe(true)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'TRUE'
+    expect(isDebugCacheEnabled()).toBe(true)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'True'
+    expect(isDebugCacheEnabled()).toBe(true)
+  })
+
+  it('should return true for "yes" (case-insensitive)', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'yes'
+    expect(isDebugCacheEnabled()).toBe(true)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'YES'
+    expect(isDebugCacheEnabled()).toBe(true)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'Yes'
+    expect(isDebugCacheEnabled()).toBe(true)
+  })
+
+  it('should handle whitespace correctly', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = ' true '
+    expect(isDebugCacheEnabled()).toBe(true)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = ' 1 '
+    expect(isDebugCacheEnabled()).toBe(true)
+  })
+
+  it('should return false for "0"', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = '0'
+    expect(isDebugCacheEnabled()).toBe(false)
+  })
+
+  it('should return false for "false" (case-insensitive)', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'false'
+    expect(isDebugCacheEnabled()).toBe(false)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'FALSE'
+    expect(isDebugCacheEnabled()).toBe(false)
+  })
+
+  it('should return false for "no" (case-insensitive)', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'no'
+    expect(isDebugCacheEnabled()).toBe(false)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'NO'
+    expect(isDebugCacheEnabled()).toBe(false)
+  })
+
+  it('should return false when undefined', () => {
+    delete process.env.NEXT_PRIVATE_DEBUG_CACHE
+    expect(isDebugCacheEnabled()).toBe(false)
+  })
+
+  it('should return false for empty string', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = ''
+    expect(isDebugCacheEnabled()).toBe(false)
+  })
+
+  it('should return false for arbitrary values', () => {
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'arbitrary'
+    expect(isDebugCacheEnabled()).toBe(false)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = 'debug'
+    expect(isDebugCacheEnabled()).toBe(false)
+
+    process.env.NEXT_PRIVATE_DEBUG_CACHE = '2'
+    expect(isDebugCacheEnabled()).toBe(false)
+  })
+})
diff --git a/packages/next/src/server/lib/debug-utils.ts b/packages/next/src/server/lib/debug-utils.ts
@@ -0,0 +1,17 @@
+/**
+ * Check if debug logging is enabled based on the NEXT_PRIVATE_DEBUG_CACHE environment variable.
+ * Debug logging is enabled only if the variable is set to one of: '1', 'true', 'yes' (case-insensitive).
+ * It is disabled if set to '0', 'false', 'no', or unset.
+ * 
+ * @returns true if debug logging should be enabled, false otherwise
+ */
+export function isDebugCacheEnabled(): boolean {
+  const value = process.env.NEXT_PRIVATE_DEBUG_CACHE
+
+  if (!value) {
+    return false
+  }
+
+  const normalizedValue = value.toLowerCase().trim()
+  return normalizedValue === '1' || normalizedValue === 'true' || normalizedValue === 'yes'
+}
diff --git a/packages/next/src/server/lib/incremental-cache/file-system-cache.ts b/packages/next/src/server/lib/incremental-cache/file-system-cache.ts
@@ -1,3 +1,4 @@
+import { isDebugCacheEnabled } from '../debug-utils'
 import type { RouteMetadata } from '../../../export/routes/types'
 import type { CacheHandler, CacheHandlerContext, CacheHandlerValue } from '.'
 import type { CacheFs } from '../../../shared/lib/utils'
@@ -38,7 +39,7 @@ export default class FileSystemCache implements CacheHandler {
   private flushToDisk?: FileSystemCacheContext['flushToDisk']
   private serverDistDir: FileSystemCacheContext['serverDistDir']
   private revalidatedTags: string[]
-  private static debug: boolean = !!process.env.NEXT_PRIVATE_DEBUG_CACHE
+  private static debug: boolean = isDebugCacheEnabled()
   private static memoryCache: LRUCache<CacheHandlerValue> | undefined
 
   constructor(ctx: FileSystemCacheContext) {

diff --git a/packages/next/src/server/lib/incremental-cache/index.ts b/packages/next/src/server/lib/incremental-cache/index.ts
@@ -1,3 +1,4 @@
+import { isDebugCacheEnabled } from '../debug-utils'
 import type { CacheFs } from '../../../shared/lib/utils'
 import type { PrerenderManifest } from '../../../build'
 import {
@@ -93,8 +94,7 @@ export class IncrementalCache implements IncrementalCacheType {
   readonly isOnDemandRevalidate?: boolean
   readonly revalidatedTags?: readonly string[]
 
-  private static readonly debug: boolean =
-    !!process.env.NEXT_PRIVATE_DEBUG_CACHE
+  private static readonly debug: boolean = isDebugCacheEnabled()
   private readonly locks = new Map<string, Promise<void>>()
 
   /**

diff --git a/packages/next/src/server/route-modules/app-route/module.ts b/packages/next/src/server/route-modules/app-route/module.ts
@@ -1,3 +1,4 @@
+import { isDebugCacheEnabled } from '../../lib/debug-utils'
 import type { NextConfig } from '../../config-shared'
 import type { AppRouteRouteDefinition } from '../../route-definitions/app-route-route-definition'
 import type { AppSegmentConfig } from '../../../build/segment-config/app/app-segment-config'
@@ -333,7 +334,7 @@ export class AppRouteRouteModule extends RouteModule<
       context.renderOpts.pendingWaitUntil = executeRevalidates(
         workStore
       ).finally(() => {
-        if (process.env.NEXT_PRIVATE_DEBUG_CACHE) {
+        if (isDebugCacheEnabled()) {
           console.log(
             'pending revalidates promise finished for:',
             requestStore.url

diff --git a/packages/next/src/server/use-cache/handlers.ts b/packages/next/src/server/use-cache/handlers.ts
@@ -1,7 +1,8 @@
 import DefaultCacheHandler from '../lib/cache-handlers/default.external'
 import type { CacheHandlerCompat } from '../lib/cache-handlers/types'
+import { isDebugCacheEnabled } from '../lib/debug-utils'
 
-const debug = process.env.NEXT_PRIVATE_DEBUG_CACHE
+const debug = isDebugCacheEnabled()
   ? (message: string, ...args: any[]) => {
       console.log(`use-cache: ${message}`, ...args)
     }

diff --git a/packages/next/src/server/use-cache/use-cache-wrapper.ts b/packages/next/src/server/use-cache/use-cache-wrapper.ts
@@ -111,9 +111,11 @@ export type UseCacheLayoutComponentProps = {
   [slot: string]: any
 }
 
+import { isDebugCacheEnabled } from '../lib/debug-utils'
+
 const isEdgeRuntime = process.env.NEXT_RUNTIME === 'edge'
 
-const debug = process.env.NEXT_PRIVATE_DEBUG_CACHE
+const debug = isDebugCacheEnabled()
   ? console.debug.bind(console, 'use-cache:')
   : undefined