vitest-dev/vitest · error · Error

TypeScript compiler returned help text instead of type…

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

When typecheck runs, Vitest captures the tsc/vue-tsc stdout and checks for help-text markers ('The TypeScript Compiler - Version' / 'COMMON COMMANDS'). Their presence means tsc could not find a tsconfig and printed its help banner instead of type errors. Vitest throws a structured error listing the configured tsconfig path and remediation steps.

Solutions

Create or restore tsconfig.json at the project root.
Point test.typecheck.tsconfig at the correct path in vitest.config.
Validate the tsconfig is well-formed JSON (run tsc --noEmit -p <path> directly to confirm).
If in a monorepo, ensure the typecheck command resolves the per-package tsconfig.

Example fix

// before
export default defineConfig({ test: { typecheck: { enabled: true, tsconfig: './tsconfig.test.json' } } })
// but ./tsconfig.test.json is missing

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

Defensive patterns

Strategy: validation

Validate before calling

import { existsSync, readFileSync } from 'node:fs'
function assertTsconfig(path) {
  if (!existsSync(path)) throw new Error('tsconfig missing: ' + path)
  JSON.parse(readFileSync(path, 'utf8'))
}

Prevention

Keep a tsconfig.json at the project root or set test.typecheck.tsconfig.
Validate tsconfig JSON before enabling typecheck.
In monorepos, point typecheck.tsconfig at the per-package config.

When it happens

Trigger: test.typecheck.enabled is on, but the tsconfig referenced by test.typecheck.tsconfig (default 'tsconfig.json') does not exist, is not valid JSON, or tsc was invoked from a cwd where it cannot discover any config, so it emits help text.

Common situations: Renamed/moved tsconfig.json, set test.typecheck.tsconfig to a wrong path, ran from a workspace root without a tsconfig, or the tsconfig file is corrupt/malformed JSON.

Related errors

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

Appendix: source

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

  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 1fa9837ec2)