Verifying that the Cache Handler works

You can verify if the cache handler is active by using either of the following methods:

Method 1: Console Logging

Add console.log statements to your cache handler:

/* ... */
const handler = {
  name: 'my-cache-handler',
  async get(key) {
    console.log('handler.get', key);
    return cacheStore.get(key);
  },
  async set(key, value) {
    console.log('handler.set', key, value);
    cacheStore.set(key, value);
  },
};
/* ... */

Execute your application as usual:

npm run build
npm run start

pnpm run build
pnpm run start

yarn build
yarn run start

bun run build
bun run start

The console should display the output the application starts and any page is opened in your browser:

handler.get ...
handler.set ...

Method 2: Debug Mode

Activate debug mode by setting the NEXT_PRIVATE_DEBUG_CACHE environment variable:

Locate or create a .env.local file in your project’s root directory and add the following:

NEXT_PRIVATE_DEBUG_CACHE=1

Build and execute your application:

npm run build
npm run start

pnpm run build
pnpm run start

yarn build
yarn run start

bun run build
bun run start

A verbose output should appear in your server console when the application starts and any page is opened in your browser:

using custom cache handler @neshca/cache-handler is not configured yet
[CacheHandler] Instance created with provided context.
[CacheHandler] Creating new CacheHandler configuration.
Connecting Redis client...
[CacheHandler] Cache configuration retrieved from onCreation hook.
Redis client connected.
[CacheHandler] [handlers: [redis-stack]] Successfully created CacheHandler configuration.
[CacheHandler] [method: get] [key: /app/with-params/dynamic-true/200] Started retrieving value in order.
[CacheHandler] [handler: redis-stack] [method: get] [key: /app/with-params/dynamic-true/200] Started retrieving value.

Note: During the build stage, it’s normal to see @neshca/cache-handler is not configured yet several times.

Troubleshooting

If the cache handler is not active:

1. Verify that the cache handler has been correctly installed, imported, and configured. Refer to the Installation and the First Steps section for guidance.

2. Ensure that the NEXT_PRIVATE_DEBUG_CACHE environment variable is set. To verify, add the following to your next.config.js file:

   next.config.js

   console.log('NEXT_PRIVATE_DEBUG_CACHE', process.env.NEXT_PRIVATE_DEBUG_CACHE);

   When you build or run your application, NEXT_PRIVATE_DEBUG_CACHE 1 should appear in your console.

3. If you’re using a third-party library to retrieve data or database records (e.g., axios, node-fetch, pg) within the App directory, ensure you’re using the unstable_cache ↗. By default, Next.js will cache only native fetch calls.