Vite environment variables are undefined inside a Docker container
import.meta.env.VITE_API_URL is undefinedShort answer
Vite replaces import.meta.env values while it builds, not when the container starts. A variable given only at runtime (docker run -e or Compose environment) comes too late. Name it with the VITE_ prefix, declare it as ARG and ENV before the build command, and pass it with --build-arg.
Fix it fast
1Find out which cause you have
Check whether the value was baked into the built files. If the string is missing from dist, the build never saw the variable.
docker run --rm my-app-image sh -c 'grep -rl "https://api.example.com" /usr/share/nginx/html | head'2Match what you see, then jump to its fix
- 1
The variable shows in docker exec my-app env, yet the page still reads undefinedThe variable is set at runtime, but Vite needed it at build timeFix - 2
Only variables named without the prefix read as undefined in client codeThe variable name has no VITE_ prefixFix - 3
The ARG line exists, but the build still sees an empty value in a multi-stage DockerfileThe ARG is declared in the wrong build stageFix
- 1
What does the error look like?
import.meta.env.VITE_API_URL is undefinedVITE_ variable shows undefined in the browser console
Cause 1 of 3
The variable is set at runtime, but Vite needed it at build time
1Check
Vite statically replaces import.meta.env at build time. A container started with -e or a Compose environment block only changes the running container, after the files were already built.
docker exec my-app env | grep VITE_
grep -n "npm run build" Dockerfile2Fix
Make the value available to the build step. Docker's build arguments are not in the container by default, so turn the argument into an environment variable inside the build stage, before npm run build.
# Dockerfile
FROM node:22 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
RUN npm run build
# build command
docker build --build-arg VITE_API_URL=https://api.example.com -t my-app-image .3Verify
The built files contain the value.
docker run --rm my-app-image sh -c 'grep -rl "https://api.example.com" /usr/share/nginx/html | head'Confirmed by vite.dev
Cause 2 of 3
The variable name has no VITE_ prefix
1Check
Vite includes only prefixed variables in client code; others, such as DB_PASSWORD, read as undefined there. The prefix can be changed with the envPrefix option.
grep -rn "import.meta.env" src | head
grep -n "envPrefix" vite.config.*2Fix
Rename the variable to start with VITE_ (or set envPrefix on purpose) and update the Dockerfile and build command to match. Never put secrets in a VITE_ variable: it is readable by anyone who loads the site.
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL3Verify
Rebuild the image and read the value in the browser console.
docker build --build-arg VITE_API_URL=https://api.example.com -t my-app-image .Confirmed by vite.dev
Cause 3 of 3
The ARG is declared in the wrong build stage
1Check
Docker does not pass a global ARG (declared before FROM) into build stages. Inside the stage, you have to repeat ARG NAME.
grep -n -E '^(ARG|FROM|ENV)' Dockerfile2Fix
Declare ARG inside the stage that runs npm run build, then ENV, in that order, before the build command.
ARG VITE_API_URL
FROM node:22 AS build
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
RUN npm run build3Verify
Build with the argument and check the output files for the value.
docker build --no-cache --build-arg VITE_API_URL=https://api.example.com -t my-app-image .Confirmed by docs.docker.com
How do I stop it coming back?
- Treat every VITE_ value as public: it is bundled into the client code.
- Build one image per environment, or load runtime settings from a config file your app fetches when it starts.
- With Docker Compose, put the value under build.args, not only under environment.
- Vite gives variables already set in the shell priority over .env files, so build-stage ENV values win.
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.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
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
Playwright cannot open a headed browser on a Linux server or in Docker
npx playwright test --headed shows no window on a Linux server
A headed browser needs a display, and a Linux server or container has none.
3 causes, each with a fixWeb apps
React dev server in Docker does not reload when you save a file
Changes appear only after docker compose restart or a rebuild
File-change events often do not cross from your host into a container, so the dev server never notices the edit.
3 causes, each with a fixWeb apps
npm install fails with 'sh: node-gyp-build: command not found'
npm error command failed
A package's install script calls node-gyp-build by name.
2 causes, each with a fixWeb apps
T3 Env stops the build with Invalid environment variables
Error: Invalid environment variables
T3 Env validates process.env against your Zod schema when the app starts or builds, and stops on the first failure.
4 causes, each with a fixWeb apps
vite build cannot find index.html, especially inside Docker
Could not resolve entry module (index.html)
Vite treats index.html as the entry of the app and looks for it in the project root, which is the folder where you run the command.
4 causes, each with a fix