vitest-dev/vitest · error · Error

Each tag defined in "test.tags" must have a "name" property,

Error message

Each tag defined in "test.tags" must have a "name" property, received: ${JSON.stringify(tag)}

What it means

Thrown during tag validation when an element of `test.tags` lacks a string `name` property. Tags are referenced by name in test filtering expressions and CLI `--testTags`, so every tag object must have a non-empty string name. A tag without a name cannot be selected and is rejected up front.

Source

Thrown at packages/vitest/src/node/config/resolveConfig.ts:262

  if ('poolOptions' in resolved) {
    logger.deprecate('`test.poolOptions` was removed in Vitest 4. All previous `poolOptions` are now top-level options. Please, refer to the migration guide: https://v4.vitest.dev/guide/migration#pool-rework')
  }

  if ('workspace' in resolved) {
    throw new Error('The `test.workspace` option was removed in Vitest 4. Please, migrate to `test.projects` instead. See https://vitest.dev/guide/projects for examples.')
  }

  resolved.pool ??= 'forks'

  resolved.project = toArray(resolved.project)
  resolved.provide ??= {}

  // shallow copy tags array to avoid mutating user config
  resolved.tags = [...resolved.tags || []]
  const definedTags = new Set<string>()
  resolved.tags.forEach((tag) => {
    if (!tag.name || typeof tag.name !== 'string') {
      throw new Error(`Each tag defined in "test.tags" must have a "name" property, received: ${JSON.stringify(tag)}`)
    }
    if (definedTags.has(tag.name)) {
      throw new Error(`Tag name "${tag.name}" is already defined in "test.tags". Tag names must be unique.`)
    }
    if (/\s/.test(tag.name)) {
      throw new Error(`Tag name "${tag.name}" is invalid. Tag names cannot contain spaces.`)
    }
    if (/[!()*|&]/.test(tag.name)) {
      throw new Error(`Tag name "${tag.name}" is invalid. Tag names cannot contain "!", "*", "&", "|", "(", or ")".`)
    }
    if (/^\s*(?:and|or|not)\s*$/i.test(tag.name)) {
      throw new Error(`Tag name "${tag.name}" is invalid. Tag names cannot be a logical operator like "and", "or", "not".`)
    }
    if (typeof tag.retry === 'object' && typeof tag.retry.condition === 'function') {
      throw new TypeError(`Tag "${tag.name}": retry.condition function cannot be used inside a config file. Use a RegExp pattern instead, or define the function in your test file.`)
    }
    if (tag.priority != null && (typeof tag.priority !== 'number' || tag.priority < 0)) {
      throw new TypeError(`Tag "${tag.name}": priority must be a non-negative number.`)

View on GitHub (pinned to d568f8ce37)

Solutions

1. Give every tag a string `name`: `test: { tags: [{ name: 'slow' }] }`.
2. If generating tags from data, map and assert each has a string name before assigning to config.
3. Validate the tags array in a unit test of your config builder.

Example fix

// before
export default defineConfig({ test: { tags: [{ color: 'red' }] } })
// after
export default defineConfig({ test: { tags: [{ name: 'smoke', color: 'red' }] } })

for (const tag of tags) {
  if (typeof tag?.name !== 'string' || tag.name.length === 0) {
    throw new Error(`tag missing string name: ${JSON.stringify(tag)}`)
  }
}

function isTag(t: unknown): t is { name: string;[k: string]: unknown } {
  return typeof t === 'object' && t !== null
    && typeof (t as any).name === 'string' && (t as any).name.length > 0
}

When it happens

Trigger: Defining `test.tags` with an entry like `{}` (empty object), `{ name: 123 }` (non-string), or `{ color: 'red' }` (missing name). The check `!tag.name || typeof tag.name !== 'string'` triggers, and JSON.stringify of the offending tag is included.

Common situations: Building tags programmatically and forgetting the name; partial tag objects from a preset; copy-paste that left only metadata fields; refactoring that renamed `name` to `label`.

AI-assisted analysis of vitest-dev/vitest@d568f8ce37 (2026-08-03). Data as JSON: /data/errors/512a729cfec9e8db.json. Report an issue: GitHub.