vitest-dev/vitest · error · Error

--shard <count> 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

Thrown when the configured shard count exceeds the number of resolved test files. Vitest shards tests by splitting the file list across shard indices, so each shard must map to at least one file; if you ask for more shards than files, some shards would receive nothing and the run is considered misconfigured. This is a hard failure unless passWithNoTests is enabled (in which case empty shards are allowed).

Source

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

  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 d568f8ce37)

Solutions

  1. Reduce the shard count (--shard=N/M, lower M) to be <= the number of test files in this run.
  2. Remove the --shard flag if you do not actually need parallel CI sharding for this small suite.
  3. If empty shards are acceptable for your CI setup, set passWithNoTests: true in the vitest config so the guard is skipped.
  4. Ensure your include globs and changed-files/dependency filters actually resolve the files you expect before sharding.

Example fix

// before (CI matrix of 4, but only 2 files match)
vitest run --shard=1/4

// after
vitest run --shard=1/2
// or allow empty shards in config:
export default defineConfig({
  test: { passWithNoTests: true },
})
Defensive patterns

Strategy: validation

Validate before calling

// Before running, confirm the shard fits the resolved spec count
import { glob } from 'tinyglobby'

async function canShard(includeGlobs, shard) {
  const files = await glob(includeGlobs, { absolute: true })
  return shard.count <= files.length
}

if (config.shard && !config.passWithNoTests) {
  const ok = await canShard(config.include, config.shard)
  if (!ok) throw new Error(`Cannot shard ${resolved} files into ${config.shard.count}`)
}

Type guard

// Validate the shard config shape and feasibility against a known file count
function isValidShard(shard, fileCount) {
  return (
    shard == null
    || (typeof shard.index === 'number'
      && typeof shard.count === 'number'
      && shard.index >= 1
      && shard.index <= shard.count
      && (shard.count <= fileCount))
  )
}

Try / catch

// Catch at the run boundary and report a friendlier message
try {
  await vitest.start()
} catch (e) {
  if (e.message.startsWith('--shard')) {
    console.error('Sharding misconfigured:', e.message)
    process.exit(1)
  }
  throw e
}

Prevention

When it happens

Trigger: Configuring config.shard with { index, count } where count > number of collected test files, OR passing --shard=N/M on the CLI with M greater than the resolved spec count, AND config.passWithNoTests is false (the default). The check is at packages/vitest/src/node/pool.ts:73 against specs.length after collecting TestSpecifications.

Common situations: Running --shard=2/4 in a CI matrix where a previous filter/changed-files flag left fewer than 4 test files; using sharding in a small project with only 1-2 test files; sharding a workspace where only one project matched the file glob this run.

Related errors

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