{"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":342,"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":324,"sourceCodeEnd":360,"githubUrl":"https://github.com/vitest-dev/vitest/blob/d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09/packages/browser/src/client/tester/runner.ts#L324-L360","documentation":"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.","triggerScenarios":"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'`.","commonSituations":"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.","solutions":["Read the wrapped error's `.cause` — it contains the real message (syntax error, module not found, etc.).","Fix the underlying issue in the test file or its imports, then re-run.","If the cause is module resolution, check `vite`/`vitest` config `optimizeDeps`/`ssr.noExternal` and that the package is browser-compatible.","Clear Vite cache (`node_modules/.vite`) if a stale transform is suspected."],"exampleFix":"// the error: Error: Failed to import test file /src/login.spec.ts\n// cause: SyntaxError: Unexpected token '}'\n\n// fix the syntax error in /src/login.spec.ts, then rerun","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await import(/* @vite-ignore */ testFilePath)\n} catch (err: any) {\n  const cause = err?.cause ?? err\n  console.error('test file failed to load:', cause)\n  // surface the real error; do not swallow\n  throw err\n}","preventionTips":["Always inspect the wrapped cause of the Failed-to-import error for the real reason.","Keep vitest and @vitest/browser versions aligned across the workspace.","Avoid importing Node-only modules in browser test files.","Use correct file extensions so Vite transforms apply."],"tags":["browser","runner","module-resolution","vite","import","test-file"],"analyzedSha":"d568f8ce3739b532d5bf2c1ee1e45e8a8a473d09","analyzedAt":"2026-08-03T20:23:56.861Z","schemaVersion":2}