import.meta.env breaks or is undefined when I run my tests
Test suite failed to runShort answer
import.meta.env is a Vite feature: Vite exposes the values and replaces them at build time. Jest is a separate tool with only experimental ESM support. Run the tests with Vitest instead, and set variables with its env option or vi.stubEnv. Only names starting with VITE_ reach client code.
Fix it fast
1Find out which cause you have
Check which test runner your npm test script uses. Jest means cause 1; Vitest means look at causes 2 and 3.
grep -n "\"test\"" package.json npm ls jest vitest2Match what you see, then jump to its fix
- 1
The failure comes from Jest, and npm ls shows jest but not vitestJest runs the code without Vite, so import.meta.env has nothing behind itFix - 2
VITE_API_URL works but API_URL is undefined in client codeThe variable has no VITE_ prefixFix - 3
undefined inside one test only, or a different value is needed per testThe test needs a value that no file or config providesFix
- 1
What does the error look like?
Test suite failed to runimport.meta.env.VITE_API_URL is undefined in a test
Cause 1 of 3
Jest runs the code without Vite, so import.meta.env has nothing behind it
1Check
Vite exposes env values on import.meta.env and replaces them at build time. Nothing in Jest's documentation provides that step, and its ESM support is experimental and needs transforms emitting ESM.
cat jest.config.* 2>/dev/null2Fix
Switch the test runner to Vitest, whose env option and vi.stubEnv work on import.meta.env.
npm uninstall jest
npm install -D vitest
# package.json
# "scripts": { "test": "vitest" }3Verify
Run the suite once.
npx vitest runConfirmed by vite.dev
Cause 2 of 3
The variable has no VITE_ prefix
1Check
Only variables starting with VITE_ are exposed to client code; others come back undefined.
grep -rn "import.meta.env\." src/2Fix
Rename the variable to start with VITE_ everywhere it is defined and read.
# .env
VITE_API_URL=http://localhost:30003Verify
Read the value in a one-line test.
npx vitest runConfirmed by vite.dev
Cause 3 of 3
The test needs a value that no file or config provides
1Check
Vitest's env option sets variables for the test run on both process.env and import.meta.env, and vi.stubEnv changes them inside a test.
cat vite.config.* vitest.config.* 2>/dev/null2Fix
Set the variable in the test config for the whole run, or stub it per test and restore it afterwards.
// vitest.config.ts
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: { env: { VITE_API_URL: 'http://localhost:3000' } },
})
// in a test file
import { vi, afterEach } from 'vitest'
vi.stubEnv('VITE_API_URL', 'http://test.local')
afterEach(() => vi.unstubAllEnvs())3Verify
Assert on the value in the test and run it.
npx vitest runConfirmed by vitest.dev
How do I stop it coming back?
- Pick the test runner that matches the bundler: Vitest for Vite projects.
- Read import.meta.env in one small config module, so tests stub one place.
- Always restore stubbed values with vi.unstubAllEnvs in afterEach.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
tsconfig rejects allowImportingTsExtensions
An error that allowImportingTsExtensions needs noEmit or emitDeclarationOnly
allowImportingTsExtensions lets files import each other with .ts or .tsx extensions, and TypeScript only allows it together with noEmit or emitDeclarationOnly.
2 causes, each with a fixWeb apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
AxiosError Network Error with code ERR_NETWORK in a React app
Network Error
ERR_NETWORK means the request produced no readable response.
4 causes, each with a fixWeb apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Can't resolve '../axios' in a React project
Module not found: Error: Can't resolve '../axios'
A path that starts with ./ or ../ is a file path, not the axios package.
3 causes, each with a fix