What causes "Tag "${tag.name}": priority must be a non-negative number." in vitest-dev/vitest?

Set `priority` to a non-negative number (0, 1, 2, ...) or omit it entirely.

vitest-dev/vitest · error · TypeError

Tag " ": priority must be a non-negative number.

Error message

Tag "${tag.name}": priority must be a non-negative number.

What it means

Vitest validates each entry in `test.tags` during config resolution. A tag may carry an optional `priority` used to order tag-based test selection; that priority must be a finite non-negative number. The guard fires when `tag.priority` is set but is either not a number (e.g. a string like "high") or a negative number, throwing a TypeError with the offending tag's name.

Solutions

Set `priority` to a non-negative number (0, 1, 2, ...) or omit it entirely.
If you intended qualitative tiers, map them to numbers yourself before passing to config.
Re-check the tag entry named in the error message and fix only that object.

Example fix

// before
test: { tags: [{ name: 'smoke', priority: -1 }] }
// after
test: { tags: [{ name: 'smoke', priority: 0 }] }

Defensive patterns

Strategy: validation

Validate before calling

const tags = [
  // ...your tags
]
for (const t of tags) {
  if (t.priority != null && (typeof t.priority !== 'number' || !Number.isFinite(t.priority) || t.priority < 0)) {
    throw new Error(`Tag "${t.name}" has invalid priority: ${String(t.priority)}`)
  }
}
export default defineConfig({ test: { tags } })

Type guard

function isValidTagPriority(p: unknown): p is number {
  return typeof p === 'number' && Number.isFinite(p) && p >= 0
}

Try / catch

try {
  await createVitest('test', { test: { tags } })
} catch (err) {
  if (err instanceof Error && /priority must be a non-negative number/.test(err.message)) {
    // surface the offending tag and re-run with corrected config
  }
  throw err
}

Prevention

Keep a typed TagsConfig interface and lint against unknown values.
Generate tags from a single source-of-truth table where priority is declared as number.

When it happens

Trigger: Defining `test.tags = [{ name: 'smoke', priority: -1 }]` or `test.tags = [{ name: 'smoke', priority: 'high' }]`. Also triggered by `priority: NaN`, `priority: -0.5`, or passing an object/array as priority.

Common situations: Mistakenly typing priority as a string label; copy-pasting from a docs example that used a qualitative tier; computing priority from an expression that can yield a negative.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/ac94c174374e760e. Report an issue: GitHub.

Appendix: source

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

      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.`)
    }
    definedTags.add(tag.name)
  })

  resolved.name = typeof options.name === 'string'
    ? options.name
    : (options.name?.label || '')

  resolved.color = typeof options.name !== 'string' ? options.name?.color : undefined

  if (resolved.environment === 'browser') {
    throw new Error(`Looks like you set "test.environment" to "browser". To enable Browser Mode, use "test.browser.enabled" instead.`)
  }

  resolved.benchmark = {
    ...benchmarkConfigDefaults,
    ...resolved.benchmark,
  }

View on GitHub (pinned to 1fa9837ec2)