Skip to content
API ReferenceFunctionsupdateTag
You are currently viewing the Beta version of the documentation.

updateTag

updateTag allows you to update cached data on-demand for a specific cache tag from within Server Actions. This function is designed specifically for read-your-own-writes scenarios.

Usage

updateTag can only be called from within Server Actions. It cannot be used in Route Handlers, Client Components, or any other context.

If you need to invalidate cache tags in Route Handlers or other contexts, use revalidateTag instead.

Good to know: updateTag immediately expires the cached data for the specified tag, causing the next request to that resource to be a blocking revalidate/cache miss. This ensures that Server Actions can immediately see their own writes.

Parameters 

updateTag(tag: string): void;
  • tag: A string representing the cache tag associated with the data you want to update. Must not exceed 256 characters. This value is case-sensitive.

Returns

updateTag does not return a value.

Differences from revalidateTag

While both updateTag and revalidateTag invalidate cached data, they serve different purposes:

  • updateTag:

    • Can only be used in Server Actions
    • Immediately expires the cache entry (blocking revalidate on next visit)
    • Designed for read-your-own-writes scenarios

  • revalidateTag:

    • Can be used in Server Actions and Route Handlers
    • With profile="max" (recommended): Uses stale-while-revalidate semantics
    • With custom profile: Can be configured to any cache life profile for advanced usage
    • Without profile: legacy behavior which is equivalent to updateTag

Examples

Server Action with Read-Your-Own-Writes

app/actions.ts
'use server'
 
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  const title = formData.get('title')
  const content = formData.get('content')
 
  // Create the post in your database
  const post = await db.post.create({
    data: { title, content },
  })
 
  // Update the cache so the new post is immediately visible
  updateTag('posts')
  updateTag(`post-${post.id}`)
 
  // Redirect to the new post
  redirect(`/posts/${post.id}`)
}

Error when used outside Server Actions

app/api/posts/route.ts
import { updateTag } from 'next/cache'
 
export async function POST() {
  // ❌ This will throw an error
  updateTag('posts')
  // Error: updateTag can only be called from within a Server Action
 
  // ✅ Use revalidateTag instead in Route Handlers
  revalidateTag('posts', 'max')
}

When to use updateTag

Use updateTag when:

  • You're in a Server Action
  • You need immediate cache invalidation for read-your-own-writes
  • You want to ensure the next request sees updated data

Use revalidateTag instead when:

  • You're in a Route Handler or other non-action context
  • You want stale-while-revalidate semantics
  • You're building a webhook or API endpoint for cache invalidation