Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

import.meta.env values are undefined after vite build

Errorimport.meta.env.VITE_API_URL is undefined in production

Short answer

Vite copies variables into your code at build time, and only those that start with VITE_. A missing prefix, an env file for the wrong mode, or a variable set on the server after the build all give undefined. Rename the variable, put it in the right file, and rebuild.

  • Applies to Vite 8, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print what Vite sees for the production build. The keys that are listed are the only ones your code can read.

    // main.js, temporary
    console.log(import.meta.env)
  2. 2Match what you see, then jump to its fix

    1. 1The key is absent from the logged objectThe variable name has no VITE_ prefixFix
    2. 2The key is present in dev, missing in the buildThe value lives in an env file for another modeFix
    3. 3Works when you build on your laptop, undefined from the pipeline or the Docker imageThe value is set on the server or in CI after the buildFix

What does the error look like?

  • import.meta.env.VITE_API_URL is undefined in production
  • The value works with npm run dev but not after npm run build

Cause 1 of 3

The variable name has no VITE_ prefix

1Check

Only variables whose names start with VITE_ reach client code. Others, such as DB_PASSWORD, are kept out on purpose.

grep -n -v "^#" .env | cut -d= -f1

2Fix

Rename the variable to start with VITE_ and read it with that name. Do not put secrets in it, because it ends up in the public bundle.

# .env
VITE_API_URL=https://api.example.com

3Verify

Rebuild and read the value.

npm run build && grep -r "api.example.com" dist | head -n 1

Confirmed by vite.dev

Did this fix it?

Cause 2 of 3

The value lives in an env file for another mode

1Check

npm run dev uses development mode and vite build uses production mode. A file such as .env.development is not read by the build.

ls -a | grep "^.env"

2Fix

Put the value in .env, or in .env.production, or build with the mode that matches the file.

# .env.production
VITE_API_URL=https://api.example.com

# or pick a mode explicitly (loads .env.staging)
npx vite build --mode staging

3Verify

Rebuild and check the bundle.

npx vite build

Confirmed by vite.dev

Did this fix it?

Cause 3 of 3

The value is set on the server or in CI after the build

1Check

Values are statically replaced while vite build runs. Setting them later, at container start, changes nothing. The env file must exist in the build step, or the variable must be set in the command that runs it.

env | grep VITE_

2Fix

Provide the variable to the build step itself.

VITE_API_URL=https://api.example.com npx vite build

3Verify

Search the output for the value.

grep -r "api.example.com" dist | head -n 1

Confirmed by vite.dev

Did this fix it?

How do I stop it coming back?

  • Write the needed VITE_ names in a committed .env.example.
  • Set build-time variables in the same step that runs vite build.
  • Never put secrets in a VITE_ variable.

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

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.