That cacheTag import error happens because the API name, import path, or runtime support does not match the version of Next.js you are actually running.

If your app fails after adding import { unstable_cacheTag as cacheTag } from 'next/cache', the problem is usually one of three things: the export is not available in your installed Next.js version, the feature name has changed across releases, or the function is being used in a context where cache components and tag-based revalidation are not supported.

The reproduction linked in the sample repository points directly at the import line, which strongly suggests an API compatibility issue rather than an application logic bug.

Understanding the Root Cause

The new caching APIs in Next.js have gone through multiple iterations. Some releases expose unstable APIs under names like unstable_cache, while newer documentation may reference related helpers such as cacheTag or revalidateTag. If you import unstable_cacheTag but your installed framework version does not export that symbol, the build will fail with an error similar to:

Attempted import error: 'unstable_cacheTag' is not exported from 'next/cache'

This happens because ES module imports are statically analyzed. During compilation, Next.js checks whether next/cache actually exports the requested member. If it does not, the app cannot compile.

There is also a second layer to the problem: even when a tag API exists, it may require a specific App Router setup, a supported runtime, or a matching cache strategy such as tag revalidation via revalidateTag(). In short, importing the right symbol is only part of the fix; the feature must also be supported by your installed version and usage pattern.

Most often, this bug appears for one of these technical reasons:

• You copied code from newer docs but your project uses an older Next.js release.
• The correct export is cacheTag in one version, not unstable_cacheTag.
• You intended to use unstable_cache or revalidateTag, but imported the wrong API.
• Your project is not fully configured for the App Router caching model.

Step-by-Step Solution

Use the following process to identify the exact mismatch and apply the correct fix.

1. Check your installed Next.js version

npm ls next

Or with Yarn:

yarn why next

Then compare your installed version with the API shown in the official Next.js documentation. Make sure you are reading docs for the same version as your project.

2. Verify what next/cache actually supports in your version

If your code currently looks like this:

import { unstable_cacheTag as cacheTag } from 'next/cache'

replace it only after confirming which API your version supports.

Common valid alternatives include:

import { unstable_cache } from 'next/cache'

import { revalidateTag } from 'next/cache'

import { cacheTag } from 'next/cache'

If unstable_cacheTag is not exported, do not alias it and assume it exists. The module must provide the symbol directly.

3. Upgrade Next.js if you need the newer cache API

If your code is based on a newer feature, upgrade first:

npm install next@latest react@latest react-dom@latest

After upgrading, restart the dev server:

npm run dev

This matters because stale build output can sometimes make import debugging more confusing.

4. Use the correct caching primitive for your actual goal

If your goal is to cache server-side data, you may not need cacheTag directly. In many cases, one of these is the real solution:

• Cache a function with unstable_cache
• Invalidate tag-based data with revalidateTag
• Attach tags to fetch requests using Next.js fetch options

Example using tagged fetch caching:

export async function getProducts() {
  const response = await fetch('https://example.com/api/products', {
    next: { tags: ['products'] }
  })

  if (!response.ok) {
    throw new Error('Failed to fetch products')
  }

  return response.json()
}

Then invalidate that cache elsewhere:

import { revalidateTag } from 'next/cache'

export async function POST() {
  revalidateTag('products')
  return Response.json({ revalidated: true })
}

If instead you need function-level caching, use:

import { unstable_cache } from 'next/cache'

const getCachedProducts = unstable_cache(
  async () => {
    const response = await fetch('https://example.com/api/products')
    return response.json()
  },
  ['products-cache-key'],
  {
    tags: ['products']
  }
)

5. If the docs now show cacheTag, import that exact name

On versions that support the stable or current API, your import may need to be:

import { cacheTag } from 'next/cache'

Do not prepend unstable_ unless your installed version explicitly exports the unstable variant.

6. Clean and rebuild if the error persists

rm -rf .next node_modules package-lock.json
npm install
npm run dev

This removes cached artifacts and ensures the module graph is rebuilt cleanly.

7. Final recommended fix pattern

If the issue is specifically the failing import line, the safest fix is:

1. Check your Next.js version
2. Match the docs to that exact version
3. Replace unstable_cacheTag with the real exported symbol your version supports
4. Upgrade if you need the newer API

For many projects, the corrected code ends up being one of these:

import { cacheTag } from 'next/cache'

import { revalidateTag } from 'next/cache'

import { unstable_cache } from 'next/cache'

Common Edge Cases

Using Pages Router instead of App Router

Some newer cache APIs are designed primarily for the App Router. If your project still relies on the Pages Router, behavior and support may differ.

Following canary docs on a stable release

This is a very common source of import errors. The docs may describe an API that only exists in canary or a newer stable version.

Import path typos

The correct module is typically next/cache. Importing from another internal path or copying an outdated blog post can cause immediate failures.

Using tag APIs without tag-aware caching

If you call a tag invalidation API but your data was never cached with tags, nothing useful will happen even if the import works.

Server-only API used in the wrong place

Some cache APIs are intended for server components, route handlers, or other server-only contexts. Importing them into client code may fail or behave unexpectedly.

Outdated lockfile in a reproduction repo

A repository may declare one version range in package.json but resolve another version through the lockfile. Always inspect the actually installed version, not just the declared dependency.

FAQ

Why does unstable_cacheTag fail even though I saw it in examples?

Because examples may target a different Next.js release. Your installed version of next/cache must export that symbol, or the import will fail at build time.

Should I use cacheTag, revalidateTag, or unstable_cache?

Use unstable_cache to cache function results, revalidateTag to invalidate tagged cache entries, and cacheTag only if your exact Next.js version supports that API and your use case requires it.

What is the fastest way to confirm the fix?

Run npm ls next, update the import to match that version’s documented export, then restart the dev server. If the compiler no longer reports a missing export from next/cache, the issue is resolved.

The key takeaway is simple: this is not usually a broken application feature, but a version-to-API mismatch. Align the import name, framework version, and caching approach, and the error disappears.