vitest-dev/vitest · error · Error

Unknown value for "test.listTags": ${listTags}

Error message

Unknown value for "test.listTags": ${listTags}

What it means

The `test.listTags` option is typed as `boolean | 'json'`. When `vitest.listTags()` is called, core.ts:475-499 branches on those two shapes; any other value falls through to the throw at line 498 listing the offending value.

Source

Thrown at packages/vitest/src/node/core.ts:498

    else if (listTags === 'json') {
      const hasTags = [this.getRootProject(), ...this.projects].some(p => p.config.tags && p.config.tags.length > 0)
      if (!hasTags) {
        process.exitCode = 1
        this.logger.printNoTestTagsFound()
      }
      else {
        const manifest = {
          tags: this.config.tags,
          projects: this.projects.filter(p => p !== this.coreWorkspaceProject).map(p => ({
            name: p.name,
            tags: p.config.tags,
          })),
        }
        this.logger.log(JSON.stringify(manifest, null, 2))
      }
    }
    else {
      throw new Error(`Unknown value for "test.listTags": ${listTags}`)
    }
  }

  public async enableCoverage(): Promise<void> {
    this.configOverride.coverage = {} as any
    this.configOverride.coverage!.enabled = true
    await this.createCoverageProvider()
    await this.coverageProvider?.onEnabled?.()

    // onFileTransform is the only thing that affects hash
    if (this.coverageProvider?.onFileTransform) {
      this.clearAllCachePaths()
    }
  }

  public disableCoverage(): void {
    this.configOverride.coverage ??= {} as any
    this.configOverride.coverage!.enabled = false

View on GitHub (pinned to d568f8ce37)

Solutions

1. Use `listTags: true` for the default human-readable tag listing.
2. Use `listTags: 'json'` for machine-readable JSON output.
3. Remove the option entirely if you did not intend to list tags.

Example fix

// before
export default defineConfig({ test: { listTags: 'text' } })
// after
export default defineConfig({ test: { listTags: true } })

function assertValidListTags(value: unknown) {
  if (value !== undefined && value !== true && value !== false && value !== 'json') {
    throw new Error(`test.listTags must be boolean or 'json', got ${JSON.stringify(value)}`)
  }
}

function isValidListTags(value: unknown): value is boolean | 'json' {
  return value === true || value === false || value === 'json' || value === undefined
}

When it happens

Trigger: Set `listTags: 'text'`, `listTags: 'yaml'`, or `listTags: 1` in config, then invoke the listTags flow.

Common situations: Guessing a format string not in the schema; passing a number expecting truthiness; copy-pasting from a different tool's API.

Related errors

• Tag "${tag.name}": priority must be a non-negative number.
• The Vitest config does't define any "tags", cannot apply "${
• The ${prefix} "${tag}" is not defined in the configuration.
• 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/44a7677979fd77a3.json. Report an issue: GitHub.