vitest global setup file not found: how to fix

TL;DR

Vitest resolves globalSetup relative to the config file, so a wrong relative path is the most common cause of "not found" errors. Point it at the real file with a path relative to the config (or an absolute path), and make sure the module exports a default async function (it may optionally return a teardown function). Remember globalSetup runs once in a separate process before workers start, so it cannot share in-memory state with tests; use it for things like starting docker services or seeding a database.

The query

vitest global setup file not found: how to fix

Use this when

• Vitest fails at startup saying the global setup file was not found
• You moved the config or the setup file and runs broke
• Setting up dockerized services or DB seeding before tests

Not for

• setupFiles (per-worker setup) problems
• Test-time import errors
• Fixture or mock setup questions

Steps

1. Check the globalSetup path in your vitest config and resolve it relative to the config file's directory; confirm the file exists at that location. Expected output: you find the path is wrong (typo, wrong nesting level) or the file is genuinely missing.
2. Correct the path (relative to config, or absolute) and ensure the file has a default export that is an async function. Expected output: the module loads without import errors when required directly.
3. Keep global setup limited to process-level work (starting services, seeding data); move per-test setup into setupFiles. Expected output: a clear split between one-time environment work and per-worker setup.
4. Run vitest and confirm it starts, runs the global setup once, then executes tests. Expected output: no "not found" error; setup logs appear once before test output.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstjdzyS2lpDUThXGWnTxJFA