TypeScript cannot find import.meta.env in a Vite project
Property 'env' does not exist on type 'ImportMeta'.ts(2339)Short answer
TypeScript only knows import.meta.env after Vite's client types are loaded. Add vite/client to compilerOptions.types in tsconfig.json, or a vite-env.d.ts file with a triple-slash reference to it. For your own VITE_ variables, augment ImportMetaEnv in a d.ts file that has no import statements.
Fix it fast
1Find out which cause you have
Ask TypeScript which files it loads. If no file that references vite/client is in the list, the types are missing.
npx tsc --noEmit --listFiles | grep -E 'vite/client|vite-env'2Match what you see, then jump to its fix
- 1
TS2339 on every import.meta.env use, including import.meta.env.MODEVite's client types are not loadedFix - 2
vite-env.d.ts exists, but the error staysThe d.ts file with the reference is not part of the programFix - 3
The error names your variable, such as Property 'VITE_API_URL' does not exist on type 'ImportMetaEnv'Your own VITE_ variable is not declared, or the augmentation is ignoredFix
- 1
What does the error look like?
Property 'env' does not exist on type 'ImportMeta'.ts(2339)Property 'VITE_API_URL' does not exist on type 'ImportMetaEnv'
Cause 1 of 3
Vite's client types are not loaded
1Check
Look for a vite-env.d.ts file in src and for a types list in tsconfig.json. A project created by hand, or one where the file was deleted, has neither.
ls src/vite-env.d.ts
grep -n "types" tsconfig.json2Fix
Add vite/client to compilerOptions.types. Note that once types is set, only the listed packages join the global scope, so keep any other global type packages in the same array.
{
"compilerOptions": {
"types": ["vite/client"]
}
}3Verify
Run the type check again; the error on import.meta.env is gone.
npx tsc --noEmitConfirmed by vite.dev
Cause 2 of 3
The d.ts file with the reference is not part of the program
1Check
A tsconfig include list only picks up the folders it names. If the d.ts file sits outside those patterns, TypeScript never reads it.
grep -n -A3 "include" tsconfig.json2Fix
Put the file where include reaches it (src by default), then give it the reference line.
// src/vite-env.d.ts
/// <reference types="vite/client" />3Verify
The file now shows up in the list of loaded files.
npx tsc --noEmit --listFiles | grep vite-envConfirmed by typescriptlang.org
Cause 3 of 3
Your own VITE_ variable is not declared, or the augmentation is ignored
1Check
Open the d.ts file where you declared ImportMetaEnv. If it has any import statement at the top, TypeScript treats it as a module and the augmentation does not apply.
grep -n "^import" src/vite-env.d.ts2Fix
Remove the import lines from that file and declare the variables there. Keep the VITE_ prefix, because Vite only exposes variables with it to client code.
// src/vite-env.d.ts
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_URL: string
}
interface ImportMeta {
readonly env: ImportMetaEnv
}3Verify
Type check again, then read the value in code.
npx tsc --noEmit
# in code: const url = import.meta.env.VITE_API_URLConfirmed by vite.dev
How do I stop it coming back?
- Keep src/vite-env.d.ts in version control; scaffolded projects include it for this reason.
- Declare every VITE_ variable the code reads in ImportMetaEnv, so a typo fails at type check instead of at runtime.
- Never put secrets in VITE_ variables; they are bundled into client code.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Back end
import.meta.env values are undefined after vite build
The value works with npm run dev but not after npm run build
Vite copies variables into your code at build time, and only those that start with VITE_.
3 causes, each with a fixWeb 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
TypeScript refuses JSX because the jsx option is not set
TS17004: Cannot use JSX unless the '--jsx' flag is provided.
TypeScript compiles JSX only when you name the file with a .tsx extension and enable the jsx compiler option.
2 causes, each with a fixWeb apps
TypeScript rejects a component that returns an array or other non-Element
Its return type 'Element[]' is not a valid JSX element.
TypeScript before 5.1 required every component to return JSX.Element or null, so arrays, strings and Promises were rejected even though React renders them.
2 causes, each with a fixWeb apps
Cypress refuses to start with 'Your configFile is invalid'
Your configFile threw an error from: /path/to/cypress.config.ts
Cypress could not load cypress.config.js or .ts, or found something wrong in it.
5 causes, each with a fixWeb apps
ESLint cannot decide which copy of the @typescript-eslint plugin to use
The message lists two file paths for the same plugin, each with the name of the config that loaded it
ESLint found the same plugin at two different file paths and will not pick one.
3 causes, each with a fix