vitest-dev/vitest · error · Error

Failed to import test file ${filepath}

Error message

Failed to import test file ${filepath}

What it means

Thrown by the browser runner's `importFile` at runner.ts:341-342 when the dynamic `import()` of a test file (or setup file) rejects. The thrown `Error` wraps the original cause via `{ cause: err }`, so the underlying syntax/runtime/module-resolution error is preserved on `.cause`. This is the browser pool's failure to load the test module in the iframe context.

Source

Thrown at packages/browser/src/client/tester/runner.ts:342

      if (mode === 'setup' || !hash) {
        hash = Date.now().toString()
        this.hashMap.set(filepath, hash)
      }

      // on Windows we need the unit to resolve the test file
      const prefix = `/${/^\w:/.test(filepath) ? '@fs/' : ''}`
      const query = `browserv=${hash}`
      const importpath = `${prefix}${filepath}?${query}`.replace(/\/+/g, '/')
      // start tracing before the test file is imported
      const trace = this.config.browser.trace
      if (mode === 'collect' && trace !== 'off') {
        await this.commands.triggerCommand('__vitest_startTracing', [])
      }
      try {
        await import(/* @vite-ignore */ importpath)
      }
      catch (err) {
        throw new Error(`Failed to import test file ${filepath}`, { cause: err })
      }

      if (mode === 'collect' && !this.sourceMapPrefetches.has(filepath)) {
        // the file is transformed now, so the server can hand out its map;
        // request it early so onBeforeRunSuite doesn't have to wait
        this.sourceMapPrefetches.set(
          filepath,
          rpc().getBrowserFileSourceMap(filepath).catch(() => undefined),
        )
      }
    }

    trace = <T>(name: string, attributes: Record<string, any> | (() => T), cb?: () => T): T => {
      const options: import('@opentelemetry/api').SpanOptions = typeof attributes === 'object' ? { attributes } : {}
      return this._otel.$(`vitest.test.runner.${name}`, options, cb || attributes as () => T)
    }
  }
}

View on GitHub (pinned to d568f8ce37)

Solutions

1. Read the wrapped error's `.cause` — it contains the real message (syntax error, module not found, etc.).
2. Fix the underlying issue in the test file or its imports, then re-run.
3. If the cause is module resolution, check `vite`/`vitest` config `optimizeDeps`/`ssr.noExternal` and that the package is browser-compatible.
4. Clear Vite cache (`node_modules/.vite`) if a stale transform is suspected.

Example fix

// the error: Error: Failed to import test file /src/login.spec.ts
// cause: SyntaxError: Unexpected token '}'

// fix the syntax error in /src/login.spec.ts, then rerun

try {
  await import(/* @vite-ignore */ testFilePath)
} catch (err: any) {
  const cause = err?.cause ?? err
  console.error('test file failed to load:', cause)
  // surface the real error; do not swallow
  throw err
}

When it happens

Trigger: A test file with a syntax error, an unresolvable import, a named export that doesn't exist, a top-level `throw`, an invalid Vite transform, or a circular dependency that throws. Also setup files that fail to load with `mode: 'setup'`.

Common situations: Adding a new dependency the browser Vite server can't resolve. TypeScript/JSX not transformed because the file extension is wrong. Importing Node-only code in a browser test. Stale dev server cache after upgrading a package.

Related errors

• vitest/browser can be imported only inside the Browser Mode.
• Vitest Module Runner doesn't support Vite HMR events.
• [vitest] Failed to transform ${fileUrl}. Does the file exist
• Cannot find environment for ${testFilePath}
• Cannot take a screenshot without a test path

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