vitest-dev/vitest · error · Error

[vitest] Failed to transform

Error message

[vitest] Failed to transform ${fileUrl}. Does the file exist?

What it means

ViteExecutor.fetchTransformResult asks Vite to transform a module URL; if the result returns no code and the underlying error is not recognized as a module-not-found (ERR_LOAD_URL / 'Failed to load url'), it falls through to this generic 'Failed to transform ... Does the file exist?' error. It is the catch-all for transform failures that are not specifically missing-module errors.

Solutions

Verify the file at fileUrl actually exists on disk and the import path/alias resolves to it.
Run the same import through Vite directly or with test.pool='threads' to surface the real transform error.
Check vitest.config aliases (resolve.alias) and tsconfig paths match the import.
Disable suspect Vite plugins temporarily to isolate a transform-time plugin failure.

Example fix

// before: alias misconfigured
import { x } from '@/utils/missing'

// after: correct alias / existing file
import { x } from '@/utils/exists'

Defensive patterns

Strategy: try-catch

Validate before calling

import { existsSync } from 'node:fs'
import { pathToFileURL } from 'node:url'
function fileExists(url) {
  try { return existsSync(new URL(url)) } catch { return false }
}
if (!fileExists(fileUrl)) throw new Error('file missing: ' + fileUrl)

Try / catch

try {
  await viteExecutor.fetchTransformResult(fileUrl)
} catch (e) {
  if (/Failed to transform/.test(e.message)) {
    // check disk, aliases, plugins; re-run with threads pool for detail
  }
  throw e
}

Prevention

Validate import paths and aliases before running tests.
Run the failing import through Vite directly to see the real transform error.
Keep resolve.alias and tsconfig paths in sync.

When it happens

Trigger: The vm executor calls Vite's transformRequest for fileUrl and receives neither code nor a recognized not-found error. This covers genuine missing files where Vite did not surface ERR_MODULE_NOT_FOUND, plus plugin errors, syntax errors, or resolve failures inside the transform pipeline.

Common situations: Importing a file that does not exist on disk, a path alias misconfiguration, a Vite plugin throwing during transform, or a file with a syntax error that Vite could not parse. The 'Does the file exist?' hint points at the missing-file case as the most common.

Related errors

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

Appendix: source

Thrown at packages/vitest/src/runtime/vm/vite-executor.ts:68

          return result.code
        }
      }
      catch (cause: any) {
        // rethrow vite error if it cannot load the module because it's not resolved
        if (
          (typeof cause === 'object' && cause.code === 'ERR_LOAD_URL')
          || (typeof cause?.message === 'string' && cause.message.includes('Failed to load url'))
        ) {
          const error = new Error(
            `Cannot find module '${fileUrl}'`,
            { cause },
          ) as Error & { code: string }
          error.code = 'ERR_MODULE_NOT_FOUND'
          throw error
        }
      }

      throw new Error(
        `[vitest] Failed to transform ${fileUrl}. Does the file exist?`,
      )
    })
  }

  private createViteClientModule() {
    const identifier = CLIENT_ID
    const cached = this.esm.resolveCachedModule(identifier)
    if (cached) {
      return cached
    }
    const stub = this.options.viteClientModule
    const moduleKeys = Object.keys(stub)
    const module = new SyntheticModule(
      moduleKeys,
      function () {
        moduleKeys.forEach((key) => {
          this.setExport(key, stub[key])

View on GitHub (pinned to 1fa9837ec2)