vitest-dev/vitest · error · Error

--shard <index> must be a positive number less then <count>

Error message

--shard <index> must be a positive number less then <count>

What it means

The shard index must be in the range [1, count]. This fires when the index is missing, non-numeric, <= 0, or greater than count. Without a valid index Vitest cannot select which slice of files to run.

Source

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

  }

  resolved.clearScreen = resolved.clearScreen ?? viteConfig.clearScreen ?? true

  if (options.shard) {
    if (resolved.watch) {
      throw new Error('You cannot use --shard option with enabled watch')
    }

    const [indexString, countString] = options.shard.split('/')
    const index = Math.abs(Number.parseInt(indexString, 10))
    const count = Math.abs(Number.parseInt(countString, 10))

    if (Number.isNaN(count) || count <= 0) {
      throw new Error('--shard <count> must be a positive number')
    }

    if (Number.isNaN(index) || index <= 0 || index > count) {
      throw new Error(
        '--shard <index> must be a positive number less then <count>',
      )
    }

    resolved.shard = { index, count }
  }

  if (resolved.standalone && !resolved.watch) {
    throw new Error(`Vitest standalone mode requires --watch`)
  }

  if (resolved.mergeReports && resolved.watch) {
    throw new Error(`Cannot merge reports with --watch enabled`)
  }

  if (resolved.maxWorkers) {
    resolved.maxWorkers = resolveInlineWorkerOption(resolved.maxWorkers)
  }

View on GitHub (pinned to d568f8ce37)

Solutions

1. Use a 1-based index no larger than count: `--shard 1/4` through `--shard 4/4`.
2. If your CI gives a 0-based shard index, add 1: `--shard $((SHARD_INDEX + 1))/${SHARD_TOTAL}`.
3. Double-check the matrix size matches the count you pass.

Example fix

# before (CI matrix index 0..3)
vitest --shard ${INDEX}/4
# after
vitest --shard $((INDEX + 1))/4

function assertShardIndex(raw: string) {
  const [i, c] = raw.split('/').map(Number)
  if (!(i >= 1 && i <= c)) throw new Error(`Shard index must be in [1, ${c}], got ${i}`)
}

function isShardIndexInRange(raw: string): boolean {
  const [i, c] = raw.split('/').map(Number)
  return i >= 1 && i <= c
}

When it happens

Trigger: Run `vitest --shard 5/4` (index exceeds count), `vitest --shard 0/4` (zero-based mistake), or `vitest --shard abc/4`.

Common situations: CI matrix using 1-based index but the runner variable is 0-based; off-by-one when generating the matrix; typo'd index.

Related errors

• --shard <count> must be a positive number
• You cannot use --shard option with enabled watch
• Cannot merge reports with --watch enabled
• bitLength is required
• Negative numbers are not supported

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