How to Fix: Cannot pass an array of tags to `cacheTag` function

The `cacheTag` error happens because the function is designed to accept one tag at a time, not an array. If you pass `string[]` into `cacheTag`, TypeScript correctly flags the call because the API signature expects a single string tag argument per invocation.

You can review the original reproduction in the CodeSandbox example.

Understanding the Root Cause

This issue comes down to the function signature of `cacheTag`. The API is typed to receive a single tag value, typically a string. When you pass an array such as `[‘posts’, ‘users’]`, TypeScript reports an incompatibility because `string[]` is not assignable to the expected parameter type.

In practice, this usually appears in code like this:

import { cacheTag } from 'next/cache';

const tags = ['posts', 'users'];
cacheTag(tags);

The problem is not with your array itself. The problem is that `cacheTag` does not batch tags in a single call. Instead, it expects repeated calls, one for each tag. This design keeps tagging explicit and aligned with how cache invalidation metadata is attached internally.

So the key rule is simple: iterate over the array and call `cacheTag` for each string.

Step-by-Step Solution

Use one of the following patterns to apply multiple tags safely.

1. Call cacheTag once per tag

import { cacheTag } from 'next/cache';

const tags = ['posts', 'users'];

for (const tag of tags) {
  cacheTag(tag);
}

This is the most direct fix. Each tag is registered individually, matching the expected API usage.

2. Create a small helper function

If you need this in multiple places, wrap the behavior in a reusable utility.

import { cacheTag } from 'next/cache';

function applyCacheTags(tags: string[]) {
  for (const tag of tags) {
    cacheTag(tag);
  }
}

applyCacheTags(['posts', 'users', 'articles']);

This keeps your application code cleaner and avoids repeating the loop everywhere.

3. Support both a single tag and multiple tags

If your code sometimes receives one tag and sometimes many, normalize the input first.

import { cacheTag } from 'next/cache';

function applyCacheTags(tags: string | string[]) {
  const normalizedTags = Array.isArray(tags) ? tags : [tags];

  for (const tag of normalizedTags) {
    cacheTag(tag);
  }
}

applyCacheTags('posts');
applyCacheTags(['posts', 'users']);

This pattern is especially useful in shared server utilities or data-fetching helpers.

4. Use it in the correct server context

If you are working in a Next.js app, make sure `cacheTag` is used where the API is supported. A typical usage may look like this:

import { cacheTag } from 'next/cache';

export default async function Page() {
  const tags = ['posts', 'users'];

  for (const tag of tags) {
    cacheTag(tag);
  }

  return <div>Tagged cache correctly</div>;
}

If the tags are dynamic, validate them before applying them.

import { cacheTag } from 'next/cache';

function applyCacheTags(tags: string[]) {
  for (const tag of tags) {
    if (typeof tag === 'string' && tag.length > 0) {
      cacheTag(tag);
    }
  }
}

This prevents accidental invalid values from reaching the API.

Common Edge Cases

Empty arrays

If your tag list is empty, nothing will happen. That is usually fine, but if your cache invalidation logic depends on at least one tag, you should guard against missing values.

if (tags.length === 0) {
  throw new Error('At least one cache tag is required.');
}

Undefined or nullable values

If your tags come from optional data, filter them before calling `cacheTag`.

const tags = ['posts', maybeTag, anotherTag].filter(
  (tag): tag is string => typeof tag === 'string' && tag.length > 0
);

for (const tag of tags) {
  cacheTag(tag);
}

Using client-side code

If you try to use `cacheTag` in a Client Component or unsupported runtime context, you may hit separate framework errors. This issue is different from the array typing problem, but it often appears during the same refactor.

Assuming spread syntax will work

Some developers try this:

cacheTag(...tags);

That only works if the function supports multiple positional arguments. In this case, the issue is that the API is not defined as a variadic function for tag arrays in the way you are attempting to use it. The safest approach is still explicit iteration.

Mixing cache APIs

Do not confuse `cacheTag` with other Next.js caching mechanisms such as fetch caching, revalidation settings, or path-based invalidation. Tags are a specific cache invalidation strategy, and each API has its own contract.

FAQ

Can I pass multiple tags to cacheTag in one call?

Not as an array argument. If you have several tags, call `cacheTag` once for each tag, usually with a loop or helper function.

Why does TypeScript complain even though the array contains strings?

Because `string[]` and `string` are different types. The function signature requires a single string parameter, not a collection of strings.

What is the cleanest production-ready fix?

Create a small utility such as `applyCacheTags(tags: string[])` and centralize the loop there. That gives you cleaner code, input validation, and easier reuse across your app.

The practical fix is simple: stop passing the array directly, and apply each tag individually. Once your code matches the intended API contract, the TypeScript error disappears and your cache tagging behavior stays predictable.