IT Error Decoder
Vercel

How to Fix Next.js: revalidate failed for tag

Last reviewed

Error message

Failed to revalidate tag '<tag>' — unstable_cache or revalidateTag returned an error.

Tag-based revalidation only works in specific runtime contexts. Calling it at the wrong time fails silently or throws.

What this error means

Next.js' tag-based cache invalidation tried to mark cached entries as stale but failed.

Why this happens

Most common: revalidateTag called outside a Server Action or Route Handler, calling it during build time, or a stale cache reference after a deployment.

Quick fix (for end users)

  • Make sure revalidateTag is called from a Server Action or Route Handler, not during render.
  • Check the tag name matches what you used with the cache wrapper.

Admin / engineer fix

  • Use revalidateTag in a Server Action.

    command
    'use server';
import { revalidateTag } from 'next/cache';
export async function refreshData() {
  revalidateTag('users');
}

  • Tag entries when caching.

    command
    import { unstable_cache } from 'next/cache';
const getUsers = unstable_cache(async () => fetchUsers(), ['users-list'], { tags: ['users'] });

Step-by-step fix

  1. Confirm the tag is set on the cached entry.

  2. Confirm revalidateTag is called from a Server Action or Route Handler.

  3. Trigger and verify the cache is invalidated.

Affected products

Next.js · Vercel

Common variations of this error

People also see these phrasings of the same problem:

  • revalidateTag not working
  • Next.js cache not invalidating

Still broken? Try these

  • Cache invalidation is best-effort across edge regions; expect a brief lag.
  • Mismatched tag names won't error — they just don't invalidate anything.

Related errors

Related searches

  • next.js revalidatetag
  • unstable_cache tags

Frequently asked questions

What does "Next.js: revalidate failed for tag" mean?

Next.js' tag-based cache invalidation tried to mark cached entries as stale but failed.

What causes "Next.js: revalidate failed for tag"?

Most common: revalidateTag called outside a Server Action or Route Handler, calling it during build time, or a stale cache reference after a deployment.

How do I fix "Next.js: revalidate failed for tag"?

1. Confirm the tag is set on the cached entry. 2. Confirm revalidateTag is called from a Server Action or Route Handler. 3. Trigger and verify the cache is invalidated. Always test changes in a non-production environment first.

Browse more errors in Vercel: Fix Vercel deployment errors. Build failures, missing output directories, exceeded build duration, missing env vars, and module resolution issues. Or paste your own error into the error decoder tool to find a match. You can also go back to the homepage to browse common errors by topic.