From 2dd3dd8396e78c3de44dd0be2c562c457b6b6d52 Mon Sep 17 00:00:00 2001
From: Vladimir <sleuths.slews0s@icloud.com>
Date: Sat, 27 Dec 2025 15:39:36 +0100
Subject: [PATCH] fix: improve runner error when importing outside of test
 context (#9335)

---
 packages/runner/src/suite.ts             |  8 +++++++-
 test/global-setup/globalSetup/failing.ts | 10 ++++++++++
 test/global-setup/vitest.config.ts       |  1 +
 3 files changed, 18 insertions(+), 1 deletion(-)
 create mode 100644 test/global-setup/globalSetup/failing.ts

diff --git a/packages/runner/src/suite.ts b/packages/runner/src/suite.ts
index ce4f06f2a..574194fe2 100644
--- a/packages/runner/src/suite.ts
+++ b/packages/runner/src/suite.ts
@@ -187,7 +187,13 @@ let currentTestFilepath: string
 
 function assert(condition: any, message: string) {
   if (!condition) {
-    throw new Error(`Vitest failed to find ${message}. This is a bug in Vitest. Please, open an issue with reproduction.`)
+    throw new Error(
+      `Vitest failed to find ${message}. One of the following is possible:`
+      + '\n- "vitest" is imported directly without running "vitest" command'
+      + '\n- "vitest" is imported inside "globalSetup" (to fix this, use "setupFiles" instead, because "globalSetup" runs in a different context)'
+      + '\n- "vitest" is imported inside Vite / Vitest config file'
+      + '\n- Otherwise, it might be a Vitest bug. Please report it to https://github.com/vitest-dev/vitest/issues\n',
+    )
   }
 }
 
diff --git a/test/global-setup/globalSetup/failing.ts b/test/global-setup/globalSetup/failing.ts
new file mode 100644
index 000000000..5f53c640f
--- /dev/null
+++ b/test/global-setup/globalSetup/failing.ts
@@ -0,0 +1,10 @@
+import assert from 'node:assert'
+// node can import from vitest at any point
+import { beforeAll } from 'vitest'
+
+assert.throws(() => {
+  // some vitest API cannot be used outside of a test context
+  beforeAll(() => {})
+}, /Vitest failed to find the runner. One of the following is possible/)
+
+export default () => {}
diff --git a/test/global-setup/vitest.config.ts b/test/global-setup/vitest.config.ts
index cf17bb4e4..97b0b44ec 100644
--- a/test/global-setup/vitest.config.ts
+++ b/test/global-setup/vitest.config.ts
@@ -21,6 +21,7 @@ export default defineConfig({
       './globalSetup/ts-with-imports.ts',
       './globalSetup/another-vite-instance.ts',
       './globalSetup/update-env.ts',
+      './globalSetup/failing.ts',
     ],
   },
 })
-- 
2.51.2