invalid globalSetup file

Error message

invalid globalSetup file ${file}. Must export setup, teardown or have a default export

What it means

After validating types, if a globalSetup file has no default, no setup, and no teardown export, it is invalid. Every globalSetup file must provide at least one of these so Vitest has something to run. The file path is included to identify which entry in the globalSetup array failed.

Solutions

Add `export default function() {}` or `export function setup() {}` / `export function teardown() {}`.
Verify the file path in the globalSetup array points to the intended setup module.
Remove the file from the globalSetup array if it isn't actually a global setup.

Example fix

// before - empty setup file referenced in globalSetup
// ./globalSetup.ts
export const x = 1

// after
// ./globalSetup.ts
export function setup() {
  globalThis.__DB__ = connect()
}
export function teardown() {
  globalThis.__DB__.close()
}

Defensive patterns

Strategy: validation

Validate before calling

function hasGlobalSetupExport(mod) {
  return typeof mod.default === 'function'
    || typeof mod.setup === 'function'
    || typeof mod.teardown === 'function'
}
// after importing the candidate file: if (!hasGlobalSetupExport(m)) skip / fail fast

Type guard

function isGlobalSetupModule(mod): mod is { default?: Function, setup?: Function, teardown?: Function } {
  return typeof mod.default === 'function' || typeof mod.setup === 'function' || typeof mod.teardown === 'function'
}

Prevention

Scaffold new globalSetup files with at least one of default/setup/teardown.
Double-check the file path in the globalSetup array.
Remove entries from the array when the file is no longer a setup module.

When it happens

Trigger: A globalSetup file that exports nothing relevant, or only unrelated helpers/constants. The path is loaded via runner.import but yields no setup/teardown/default.

Common situations: Empty scaffold file; importing a non-globalSetup module by mistake in the globalSetup array; a refactor that removed the exports; wrong path in config.

Related errors

AI-assisted analysis of vitest-dev/vitest@1fa9837ec2 (2026-08-11). Data as JSON: /api/errors/82ea749a308d8ace. Report an issue: GitHub.

Appendix: source

Thrown at packages/vitest/src/node/globalSetup.ts:47

        `invalid export in globalSetup file ${file}: ${exp} must be a function`,
      )
    }
  }
  if (m.default) {
    return {
      file,
      setup: m.default,
    }
  }
  else if (m.setup || m.teardown) {
    return {
      file,
      setup: m.setup,
      teardown: m.teardown,
    }
  }
  else {
    throw new Error(
      `invalid globalSetup file ${file}. Must export setup, teardown or have a default export`,
    )
  }
}

View on GitHub (pinned to 1fa9837ec2)