vitest-dev/vitest · error · TypeError

File is required to collect tasks.

Error message

File is required to collect tasks.

What it means

The `SuiteCollector.collect` method (suite.ts:544-547) requires a `File` to attach collected tasks to. If `file` is null/undefined when `collect` is invoked, it throws a `TypeError`. This is an internal collection-path guard; normally the file is always provided by the orchestrator during `collectTests`.

Source

Thrown at packages/vitest/src/runtime/runner/suite.ts:546

      if (stack) {
        suite.location = {
          line: stack.line,
          column: stack.column,
        }
      }
    }

    setHooks(suite, createSuiteHooks())
  }

  function clear() {
    tasks.length = 0
    initSuite(false)
  }

  async function collect(file: File) {
    if (!file) {
      throw new TypeError('File is required to collect tasks.')
    }

    if (factory) {
      await runWithSuite(collector, () => factory(test))
    }

    const allChildren: Task[] = []

    for (const i of tasks) {
      allChildren.push(i.type === 'collector' ? await i.collect(file) : i)
    }

    suite.tasks = allChildren

    return suite
  }

  collectTask(collector)

View on GitHub (pinned to d568f8ce37)

Solutions

1. Always pass a valid `File` object when calling `collector.collect(file)`.
2. Use `collectTests(specs, runner)` which constructs and passes files internally.
3. Validate that your `FileSpecification` resolves to a non-null file before collection.

Example fix

// before
const collector = suite('x', () => {})
await collector.collect(undefined) // throws
// after
const file = { filepath: '/abs/test.ts', /* ...required File fields */ } as File
await collector.collect(file)

import type { File } from 'vitest'
function collectSafely(c: { collect(f: File): Promise<any> }, file: File | null | undefined) {
  if (!file) throw new TypeError('A valid File is required')
  return c.collect(file)
}

function isFile(v: unknown): v is File {
  return !!v && typeof (v as any).filepath === 'string'
}

When it happens

Trigger: Programmatically calling `collector.collect(undefined)` or `collector.collect(null)`; a custom collection pipeline that doesn't pass the file; a malformed `FileSpecification` that yields no file object.

Common situations: Custom runners/builders that drive collection manually; bugs in tooling that constructs `SuiteCollector` without a file context; edge cases in programmatic API usage.

Related errors

• bitLength is required
• Negative numbers are not supported
• Cannot find iframe with id ${event.iframeId}
• Cannot compare screenshots without a test path
• `resolveOptions` has to be used in a test file

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