{"record":{"id":"924a8714c6080138","repo":"vitest-dev/vitest","slug":"failed-to-import-test-file-filepath","errorCode":null,"errorMessage":"Failed to import test file ${filepath}","messagePattern":"Failed to import test file (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/src/client/tester/runner.ts","lineNumber":349,"sourceCode":"      if (mode === 'setup' || !hash) {\n        hash = Date.now().toString()\n        this.hashMap.set(filepath, hash)\n      }\n\n      // on Windows we need the unit to resolve the test file\n      const prefix = `/${/^\\w:/.test(filepath) ? '@fs/' : ''}`\n      const query = `browserv=${hash}`\n      const importpath = `${prefix}${filepath}?${query}`.replace(/\\/+/g, '/')\n      // start tracing before the test file is imported\n      const trace = this.config.browser.trace\n      if (mode === 'collect' && trace !== 'off') {\n        await this.commands.triggerCommand('__vitest_startTracing', [])\n      }\n      try {\n        await import(/* @vite-ignore */ importpath)\n      }\n      catch (err) {\n        throw new Error(`Failed to import test file ${filepath}`, { cause: err })\n      }\n\n      if (mode === 'collect' && !this.sourceMapPrefetches.has(filepath)) {\n        // the file is transformed now, so the server can hand out its map;\n        // request it early so onBeforeRunSuite doesn't have to wait\n        this.sourceMapPrefetches.set(\n          filepath,\n          rpc().getBrowserFileSourceMap(filepath).catch(() => undefined),\n        )\n      }\n    }\n\n    trace = <T>(name: string, attributes: Record<string, any> | (() => T), cb?: () => T): T => {\n      const options: import('@opentelemetry/api').SpanOptions = typeof attributes === 'object' ? { attributes } : {}\n      return this._otel.$(`vitest.test.runner.${name}`, options, cb || attributes as () => T)\n    }\n  }\n}","sourceCodeStart":331,"sourceCodeEnd":367,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/src/client/tester/runner.ts#L331-L367","documentation":"Thrown by the browser runner when the dynamic `import()` of a test file fails. The runner constructs an import URL (`/<filepath>?browserv=<hash>`, with `@fs/` prefix on Windows paths) and lets Vite transform it; if Vite/the browser cannot resolve, transform, or execute the module, the import promise rejects. The original rejection is attached as `cause` so the underlying syntax/resolution/runtime error is preserved.","triggerScenarios":"A syntax error in the test file; an import of a module that does not exist or is not installed; a Vite transform error (e.g. invalid TypeScript, unsupported syntax for the target); a circular/failed setup-file import; the file path being inaccessible on the Vite server.","commonSituations":"New dependency not yet installed (`pnpm install`); typo in an import path; using a Node-only API in a browser test; TypeScript types referencing a missing module; stale Vite cache after upgrading.","solutions":["Inspect `error.cause` (printed in the Vitest report) — it holds the real module load/transform error.","Fix the underlying syntax/import error in the test file or its dependencies.","Run `pnpm install` if a package is missing; clear the Vite cache (`node_modules/.vite`) if stale.","Confirm the path is served by the Vite dev server (no typos, correct case, inside `root`)."],"exampleFix":"// error.cause: Cannot find module '@/utils'\n// before\nimport { x } from '@/utils'\n\n// after (fix the path / install the package)\nimport { x } from './utils'","handlingStrategy":"try-catch","validationCode":"// pre-flight: resolve the test file the same way Vite would\ntry {\n  await import(/* @vite-ignore */ testFilePath)\n} catch (e) {\n  console.error('Test file will fail to import:', e)\n}","typeGuard":null,"tryCatchPattern":"// the runner already wraps the import; surface error.cause to the user\ntry {\n  await runTests()\n} catch (err) {\n  const cause = (err as Error & { cause?: Error }).cause\n  if (cause) console.error('Underlying import error:', cause)\n  throw err\n}","preventionTips":["Always inspect `error.cause` for the real import/transform failure.","Run `pnpm install` after adding dependencies.","Keep test imports resolvable by Vite (correct paths, case, inside root).","Clear `node_modules/.vite` after upgrades to avoid stale caches."],"tags":["runner","browser","module-resolution","vite","import"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}