vitest-dev/vitest · error · Error

TypeScript compiler returned help text instead of type check

Error message

TypeScript compiler returned help text instead of type checking results.
This usually means the tsconfig file was not found.

Possible solutions:
  1. Ensure '${tsconfigPath}' exists in your project root
  2. If using a custom tsconfig, verify the path in your Vitest config:
     test: { typecheck: { tsconfig: 'path/to/tsconfig.json' } }
  3. Check that the tsconfig file is valid JSON

What it means

The typechecker inspects tsc/vue-tsc stdout and, if it contains the compiler help banner ('The TypeScript Compiler - Version' or 'COMMON COMMANDS'), concludes no tsconfig was found and throws (typechecker.ts:128-140). tsc prints help text exactly when it is invoked without a resolvable tsconfig via -p/--build.

Source

Thrown at packages/vitest/src/typecheck/typechecker.ts:139

  protected async prepareResults(output: string): Promise<{
    files: File[]
    sourceErrors: TestError[]
    time: number
  }> {
    // Detect if tsc output is help text instead of error output
    // This happens when tsconfig.json is missing and tsc can't find any config
    if (output.includes('The TypeScript Compiler - Version') || output.includes('COMMON COMMANDS')) {
      const { typecheck } = this.project.config
      const tsconfigPath = typecheck.tsconfig || 'tsconfig.json'
      const msg = `TypeScript compiler returned help text instead of type checking results.\n`
        + `This usually means the tsconfig file was not found.\n\n`
        + `Possible solutions:\n`
        + `  1. Ensure '${tsconfigPath}' exists in your project root\n`
        + `  2. If using a custom tsconfig, verify the path in your Vitest config:\n`
        + `     test: { typecheck: { tsconfig: 'path/to/tsconfig.json' } }\n`
        + `  3. Check that the tsconfig file is valid JSON`

      throw new Error(msg)
    }

    const typeErrors = await this.parseTscLikeOutput(output)
    const testFiles = new Set(this.getFiles())

    if (!this._tests) {
      this._tests = await this.collectTests()
    }

    const sourceErrors: TestError[] = []
    const files: File[] = []

    testFiles.forEach((path) => {
      const { file, definitions, map, parsed } = this._tests![path]
      const errors = typeErrors.get(path)
      files.push(file)
      if (!errors) {
        this.markPassed(file)

View on GitHub (pinned to d568f8ce37)

Solutions

1. Confirm the tsconfig file (default tsconfig.json) exists at config.root.
2. Set test.typecheck.tsconfig to the correct relative or absolute path in vitest.config.
3. Validate the tsconfig is parseable JSON (run `tsc --noEmit -p <path>` manually to verify).
4. Ensure config.root points at the directory containing the tsconfig.

Example fix

// before: wrong tsconfig path
export default defineConfig({
  test: { typecheck: { tsconfig: './tsconfigs/main.json' } },
})

// after: correct path
export default defineConfig({
  test: { typecheck: { tsconfig: './tsconfig.json' } },
})

import { existsSync } from 'node:fs'
import { resolve } from 'node:path'

function assertTsconfigExists(root: string, tsconfig?: string) {
  const path = resolve(root, tsconfig || 'tsconfig.json')
  if (!existsSync(path)) {
    throw new Error(`tsconfig not found at '${path}' (configured typecheck.tsconfig)`)
  }
}

When it happens

Trigger: Enabling test.typecheck with a tsconfig path that does not exist, is a directory without tsconfig.json, or is unreachable because the root/cwd is wrong. The checker is spawned with `-p <tsconfigPath>` (or --build) and tsc emits its help banner instead of diagnostics.

Common situations: Renamed/moved tsconfig.json; set typecheck.tsconfig to a relative path that does not resolve from config.root; monorepo where the tsconfig lives in a package subdir but root points elsewhere; fresh checkout that did not generate a tsconfig.

Related errors

• You've enabled headless mode for "preview" provider but it d
• vitest/browser can be imported only inside the Browser Mode.
• toHaveFormValues must be called with an object of expected f
• ${name}Browser name is required. Please, set `test.browser.i
• Browser Mode requires the "provider" to always be specified.

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