vitest-dev/vitest · error · Error

The ${prefix} "${tag}" is not defined in the configuration.

Error message

The ${prefix} "${tag}" is not defined in the configuration. Available tags are:
${availableTags.map(t => `- ${t.name}${t.description ? `: ${t.description}` : ''}`).join('\n')}

What it means

Thrown by createNoTagsError when a test references a tag (via the @tag annotation) or a tag-filter expression references a tag/wildcard pattern that is not declared in the `tags` array of the Vitest config. The error lists every defined tag name and description so the developer can see exactly what is allowed. It only fires for test annotations when `config.strictTags` is true, but tag-filter resolution always validates against the defined tags.

Source

Thrown at packages/vitest/src/runtime/runner/utils/tags.ts:41

export function validateTags(config: SerializedConfig, tags: string[]): void {
  if (!config.strictTags) {
    return
  }

  const availableTags = new Set(config.tags.map(tag => tag.name))
  for (const tag of tags) {
    if (!availableTags.has(tag)) {
      throw createNoTagsError(config.tags, tag)
    }
  }
}

export function createNoTagsError(availableTags: TestTagDefinition[], tag: string, prefix = 'tag'): never {
  if (!availableTags.length) {
    throw new Error(`The Vitest config does't define any "tags", cannot apply "${tag}" ${prefix} for this test. See: https://vitest.dev/guide/test-tags`)
  }
  throw new Error(`The ${prefix} "${tag}" is not defined in the configuration. Available tags are:\n${availableTags
    .map(t => `- ${t.name}${t.description ? `: ${t.description}` : ''}`)
    .join('\n')}`)
}

export function createTagsFilter(tagsExpr: string[], availableTags: TestTagDefinition[]): (testTags: string[]) => boolean {
  const matchers = tagsExpr.map(expr => parseTagsExpression(expr, availableTags))
  return (testTags: string[]) => {
    return matchers.every(matcher => matcher(testTags))
  }
}

type TagMatcher = (tags: string[]) => boolean

function parseTagsExpression(expr: string, availableTags: TestTagDefinition[]): TagMatcher {
  const tokens = tokenize(expr)
  const stream = new TokenStream(tokens, expr)
  const ast = parseOrExpression(stream, availableTags)
  if (stream.peek().type !== 'EOF') {

View on GitHub (pinned to d568f8ce37)

Solutions

1. Add the missing tag name to the `tags` array in vitest.config: `tags: [{ name: 'integration', description: '...' }]`.
2. Fix the typo in the test annotation or filter expression so it matches an already-declared tag name exactly.
3. If the tag should be allowed freely without config registration, set `strictTags: false` (or omit it).
4. For wildcard filters, verify the pattern matches at least one declared tag name.

Example fix

// before
export default defineConfig({
  test: { strictTags: true, tags: [{ name: 'unit' }] }
})
it('x', () => {}, { tags: ['integration'] }) // throws

// after
export default defineConfig({
  test: { strictTags: true, tags: [{ name: 'unit' }, { name: 'integration' }] }
})

// Before annotating tests, check the tag exists in config
import config from './vitest.config'
const declared = new Set((config.test?.tags ?? []).map(t => t.name))
function assertTagKnown(tag: string) {
  if (!declared.has(tag)) {
    throw new Error(`Tag '${tag}' is not declared in config.test.tags`)
  }
}
assertTagKnown('integration')

import type { TestTagDefinition } from 'vitest'
function isKnownTag(tag: string, defined: TestTagDefinition[]): tag is string {
  return defined.some(t => t.name === tag)
}

When it happens

Trigger: Called from validateTags (line 32, prefix='tag') when strictTags is enabled and a test decorator like `it('x', () => {}, { tags: ['slow'] })` names a tag absent from config.tags. Also called from resolveTagPattern (lines 273/279, prefix='tag pattern') when a --tag filter like `--tag 'smoke*'` or `--tag unit` has no match among defined tags.

Common situations: Enabling `strictTags: true` to catch typos, then having a test annotated with a tag that was never registered. Migrating test suites where tags were free-form strings before adopting the config-defined tag system. Running `vitest --tag integration` without having declared `integration` in config.tags. Typing a tag differently in the test vs the config (e.g. 'smoke-test' vs 'smoke').

Related errors

• Tag "${tag.name}": priority must be a non-negative number.
• Unknown value for "test.listTags": ${listTags}
• The Vitest config does't define any "tags", cannot apply "${
• Environment "${name}" is not a valid environment. Path "${pa
• Tag "${tag.name}": retry.condition function cannot be used i

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