vitest-dev/vitest · error

--shard must be a smaller than count of test files…

Error message

--shard <count> must be a smaller than count of test files. Resolved ${specs.length} test files for --shard=${ctx.config.shard.index}/${ctx.config.shard.count}.

What it means

Sharding splits the resolved test files into N shards; shard.count must not exceed the number of matched files (unless passWithNoTests is set). Asking for more shards than files makes distribution impossible and Vitest throws with the resolved counts.

Solutions

  1. Reduce --shard count to be <= the number of matched test files.
  2. Pass --pass-with-no-tests (or set passWithNoTests: true) to allow empty shards.
  3. Widen include globs / loosen filters so more files match the shard.

Example fix

// before - 10 shards but only 4 files
vitest run --shard 1/10

// after
vitest run --shard 1/4
// or
vitest run --shard 1/10 --pass-with-no-tests
Defensive patterns

Strategy: validation

Validate before calling

function shardIsValid(shard, specsLength) {
  return !shard || shard.count <= specsLength
}
// before run: if (!shardIsValid(config.shard, specs.length)) reduce shard.count or set passWithNoTests

Try / catch

try {
  await vitest.runFiles(specs)
} catch (e) {
  if (/shard/i.test(e.message) && /smaller than count of test files/i.test(e.message)) {
    // reduce shard.count or pass --pass-with-no-tests, then retry
  } else throw e
}

Prevention

When it happens

Trigger: --shard i/N (or config.test.shard = { index, count }) where shard.count > number of resolved specs, without passWithNoTests. The error embeds specs.length and the shard index/count.

Common situations: Over-sharding a small suite; sharding after a filter that reduces file count; CI matrix wider than the test count.

Related errors

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

Appendix: source

Thrown at packages/vitest/src/node/pool.ts:65

  const pool = new Pool({
    distPath: ctx.distPath,
    teardownTimeout: ctx.config.teardownTimeout,
    state: ctx.state,
  }, ctx.logger)

  const options = resolveOptions(ctx)

  const Sequencer = ctx.config.sequence.sequencer
  const sequencer = new Sequencer(ctx)

  let browserPool: ProcessPool | undefined

  async function executeTests(method: 'run' | 'collect', specs: TestSpecification[], invalidates?: string[]): Promise<void> {
    ctx.onCancel(() => pool.cancel())

    if (ctx.config.shard) {
      if (!ctx.config.passWithNoTests && ctx.config.shard.count > specs.length) {
        throw new Error(
          '--shard <count> must be a smaller than count of test files. '
          + `Resolved ${specs.length} test files for --shard=${ctx.config.shard.index}/${ctx.config.shard.count}.`,
        )
      }
      specs = await sequencer.shard(Array.from(specs))
    }

    const taskGroups: {
      tasks: PoolTask[]
      maxWorkers: number
      // browser pool has a more complex logic, so we keep it separately for now
      browserSpecs: TestSpecification[]
    }[] = []
    let workerId = 1

    const sorted = await sequencer.sort(specs)
    const { environments, tags } = await getSpecificationsOptions(specs)
    const groups = groupSpecs(sorted, environments)

View on GitHub (pinned to 1fa9837ec2)